Sync from GitHub with Git LFS

docs/HMP-0005.md

@@ -6605,10 +6605,260 @@ It improves performance and usability while preserving HMP’s core principles:
 
 ---
 
+### 12.5 Competence and Profile Containers
+
+HMP allows optional extensions of `peer_announce` that provide structured and semantically rich descriptions of agent capabilities, competences, and supported protocols.
+
+Such extensions improve discoverability, routing, interoperability, and long-term evolution of the mesh.
+
+#### 12.5.1 Protocol Awareness and Interoperability
+
+An important optional extension is the ability for agents to explicitly advertise the protocol versions and external cognitive frameworks they support.
+
+This allows:
+
+* graceful evolution of the HMP protocol;
+* coexistence of multiple HMP versions in the same mesh;
+* emergence of bridge agents capable of translating between protocols;
+* interoperability with external reasoning ecosystems.
+
+A future extension of `peer_announce` may include a `protocols` field:
+
+```json
+{
+  "head": {
+    "class": "peer_announce"
+  },
+  "payload": {
+    "capabilities": ["store-forward", "vote", "consensus"],
+    "protocols": [
+      "HMP v5.0",
+      "HMP v4.1",
+      "OpenCog Hyperon v0.6"
+    ]
+  }
+}
+```
+
+The `protocols` field is informational and non-binding.
+It does not imply full compliance with all listed specifications,
+but signals compatibility, partial support, or bridge capabilities.
+
+Nodes may use this information for:
+
+* protocol negotiation;
+* compatibility checks;
+* routing decisions;
+* selection of translators or bridge agents.
+
+This extension is optional and not required for HMP v5.0 compliance.
+
+---
+
+#### 12.5.2 External Protocol Identifiers (`peer_announce.other_protocols`)
+
+This section defines a recommended extension to `peer_announce` that allows an agent to advertise identifiers, roles, or capabilities associated with **external or meta-protocols**, without imposing normative behavior on HMP nodes.
+
+The extension is intended to:
+
+* improve interoperability with other agent ecosystems (ANP, Agora, A2A, MCP, etc.);
+* support protocol negotiation or delegation at higher layers;
+* allow agents to expose **multiple identities** across different protocol domains.
+
+All information provided by this extension is **purely declarative**.  
+Peers MAY use it for discovery or routing decisions, but MUST NOT assume full compliance with the referenced protocols.
+
+##### Example
+
+```json
+{
+  "head": { "class": "peer_announce" },
+  "payload": {
+    "other_protocols": {
+      "ANP": {
+        "name": "Agent Network Protocol",
+        "source": "https://github.com/agent-network-protocol/AgentNetworkProtocol",
+        "agent_did": "did:anp:xyz123",
+        "public_key": "base64:ABCDEF...",
+        "roles": ["router", "translator"]
+      },
+      "Agora": {
+        "name": "Agora Protocol",
+        "roles": ["negotiator"],
+        "capabilities": ["protocol-selection", "schema-adaptation"]
+      }
+    }
+  }
+}
+```
+
+Notes:
+
+* No validation or handshake is required by HMP.
+* Roles and capabilities are advisory.
+* This extension complements existing `protocols`, `roles` and `capabilities` fields.
+
+---
+
+#### 12.5.3 External Resources and External Container Storage (`peer_announce.external`)
+
+This section defines a recommended mechanism for advertising **external cognitive resources**, including container storage, mirrors, or rarely changing artifacts.
+
+The mechanism is intended to:
+
+- reduce unnecessary container transmission above the protocol;
+- allow static or large data to be accessed via standard transports (HTTP, FTP, magnet links, etc.);
+- support redundancy, mirroring, and trust-aware discovery.
+
+The presence of an external resource reference does **not** imply availability, reachability, authenticity, or trust.
+
+Use of this mechanism is optional.  
+Agents MAY ignore external references entirely without affecting protocol compliance.
+
+##### Example
+```json
+{
+  "head": { "class": "peer_announce" },
+  "payload": {
+    "external": {
+      "https, main": {
+        "source": "https://example.org/",
+        "folders": {
+          "hmp/main": {
+            "hmp_container": true,
+            "title": "container_index and semantic_index",
+            "index": "index.json",
+            "types": ["json"]
+          },
+          "hmp/meta": {
+            "hmp_container": true,
+            "title": "Abstraction and axis containers",
+            "index": "index.json",
+            "types": ["json"]
+          },
+          "hmp/peer_announces": {
+            "hmp_container": true,
+            "title": "List of known HMP nodes",
+            "index": "index.json",
+            "types": ["json"]
+          },
+          "hmp/trust": {
+            "hmp_container": true,
+            "title": "Reputation containers",
+            "index": "index.json",
+            "types": ["json"]
+          },
+          "hmp/semantic": {
+            "hmp_container": true,
+            "title": "Semantic nodes and links",
+            "index": "index.json",
+            "types": ["json"]
+          },
+          ".well-known": {
+            "hmp_container": false,
+            "title": "Public agent descriptors (ANP, A2A, Agora, etc.)",
+            "index": "index.json",
+            "types": ["json"]
+          }
+        }
+      },
+      "ftp, work": {
+        "source": "ftp://example.org/",
+        "folders": {
+          "task": {
+            "hmp_container": true,
+            "title": "Current goals and tasks",
+            "types": ["json"]
+          },
+          "books/tech": {
+            "hmp_container": false,
+            "title": "Technical literature",
+            "types": ["txt", "md", "pdf"]
+          }
+        }
+      },
+      "magnet, archive": {
+        "source": "magnet:?xt=urn:btih:...",
+        "description": "Archived materials (legacy data)"
+      }
+    }
+  }
+}
+```
+
+Notes:
+- External resources may contain HMP containers or arbitrary files.
+- Authentication mechanisms are out of scope.
+- Trust, availability, and freshness are advisory hints only.
+- Implementations MAY use folder-level metadata (such as `hmp_container`) as a hint for indexing, caching, or deferred retrieval policies.
+- Keys such as `"https, main"` are illustrative, human-readable labels only; no naming scheme or key format is mandated by this specification.
+- The effective resource path is constructed by combining the `"source"` URI with the corresponding folder path. If an `"index"` field is present, it is interpreted as a relative path within that folder.
+- The `peer_announces` folder MAY contain cached or mirrored `peer_announce` containers of other agents, obtained via direct exchange, gossip, or trusted sources.
+
+##### Index Files (Optional)
+
+A folder entry in `peer_announce.external` MAY include an optional `"index"` field, which specifies a relative path to an index file located within that folder (e.g. `"index": "index.json"`).
+
+If present, the index file MAY be used by clients to:
+- discover files available in the folder;
+- obtain descriptive metadata (titles, timestamps, hashes);
+- selectively fetch or verify external resources.
+
+The structure and semantics of the index file are **not rigidly defined by HMP** and are provided as a **recommended, non-normative convention**.  
+Implementations are free to use alternative formats or schemas.
+
+**Example 1** (HMP container index)
+```json
+{
+  "path": "https://example.org/hmp/main",
+  "title": "container_index and semantic_index",
+  "files": {
+    "container_index.json": {
+      "description": "container_index from 2026-01-25 21:49",
+      "timestamp": "2026-01-25T21:49:00Z",
+      "hmp_container_class": "container_index",
+      "mime-type": "application/ld+json",
+      "hash": "sha256:abc123..."
+    },
+    "semantic_index.json": {
+      "description": "semantic_index from 2026-01-25 21:49",
+      "timestamp": "2026-01-25T21:49:00Z",
+      "hmp_container_class": "semantic_index",
+      "mime-type": "application/ld+json",
+      "hash": "sha256:abc123..."
+    }
+  }
+}
+```
+
+**Example 2** (Documentation / static files)
+```json
+{
+  "path": "https://github.com/kagvi13/HMP/blob/main/docs/",
+  "title": "HMP 5.0 Specification Documents",
+  "files": {
+    "Grok_HMP&ANP.md": {
+      "description": "Grok (xAI): comparative analysis of HMP and ANP (January 2026)",
+      "timestamp": "2026-01-22T08:46:00Z",
+      "mime-type": "text/markdown",
+      "hash": "sha256:abc123..."
+    }
+  }
+}
+```
+
+Updating an index file does **not** require reissuing `peer_announce`.  
+All fields in the index file are optional.  
+Clients MAY ignore the index entirely and interact with the external resource directly.
+
+---
+
 ## 13. Experimental Extensions
 
 Experimental Extensions describe mechanisms that are intentionally exposed for exploration, prototyping, and architectural discovery.
 
+Experimental features are not required for protocol compliance and MAY be ignored by implementations.
+
 They may evolve rapidly, change structure, or be removed entirely based on implementation feedback.
 
 Agents implementing Experimental Extensions SHOULD assume:
@@ -6619,7 +6869,7 @@ Agents implementing Experimental Extensions SHOULD assume:
 
 Agents MUST safely ignore unsupported experimental features and MUST NOT assume their presence in peer environments.
 
-Experimental Extensions MUST NOT redefine or violate core protocol semantics, even when exploring novel architectural directions or when widely adopted.
+Experimental Extensions MUST NOT redefine or violate core protocol semantics.
 
 This section exists to encourage innovation without prematurely constraining the design space of HMP.
 
@@ -6627,6 +6877,43 @@ Implementers are explicitly invited to experiment, fork ideas, and propose refin
 
 ---
 
+### 13.1 Key Rotation and Recovery
+
+This section describes experimental extensions to `peer_announce` for key rotation and recovery.
+
+```json
+"recovery_keys": [...],
+"key_history": [...],
+"key_rotation_policy": "3-of-5"
+```
+
+One possible key management model:
+
+* rotating the **primary** key requires signatures from **all** recovery keys
+  (or an N-of-M policy);
+
+* rotating a **recovery key** requires
+
+    * a signature from the primary key, **or**
+    * a majority of recovery keys.
+
+This model aims to reduce the risk of:
+
+* DID hijacking;
+* irreversible loss of access.
+
+The semantics and security properties of these mechanisms remain subject to further experimentation.
+
+Key invalidation is part of the core HMP protocol (see Section 4.1) and is defined using:
+
+```json
+"key_is_falsified": true
+```
+
+This mechanism remains compatible with proposed extensions.
+
+---
+
 ## 14. Research Directions
 
 This section outlines optional modules and evolutionary directions that align with the architecture of HMP v5.0 but are **not part of the core specification**.
@@ -6784,36 +7071,7 @@ A strict mapping DID ↔ agent is required:
 
 #### 14.3.2 Key Rotation and Recovery
 
-Future versions may extend `peer_announce` with:
-
-```json
-"recovery_keys": [...],
-"key_history": [...],
-"key_rotation_policy": "3-of-5"
-```
-
-Key management rules:
-
-* rotating the **primary** key requires signatures from **all** recovery keys
-  (or an N-of-M policy);
-
-* rotating a **recovery key** requires
-
-    * a signature from the primary key, **or**
-    * a majority of recovery keys.
-
-This prevents:
-
-* DID hijacking;
-* irreversible loss of access.
-
-Key invalidation currently uses:
-
-```json
-"key_is_falsified": true
-```
-
-This mechanism remains compatible with proposed extensions.
+*Moved to Section 13 (Experimental Extensions).*
 
 ---
 
@@ -6896,71 +7154,7 @@ Required components:
 
 #### 14.6.4 Competence and Profile Containers
 
-Future versions of HMP may introduce more structured and semantically rich variants of `peer_announce`, allowing agents to explicitly describe their capabilities, competences, and supported protocols.
-
-Possible extensions include:
-
-* standardized competence descriptors (skills, domains, self-rated expertise);
-* machine-readable profiles usable for task routing and delegation.
-
-##### Protocol Awareness and Interoperability
-
-An important extension is the ability for agents to explicitly advertise
-the protocol versions and external cognitive frameworks they support.
-
-This allows:
-
-* graceful evolution of the HMP protocol;
-* coexistence of multiple HMP versions in the same mesh;
-* emergence of bridge agents capable of translating between protocols;
-* interoperability with external reasoning ecosystems.
-
-A future extension of `peer_announce` may include a `protocols` field:
-
-```json
-{
-  "head": {
-    "class": "peer_announce"
-  },
-  "payload": {
-    "capabilities": ["store-forward", "vote", "consensus"],
-    "protocols": [
-      "HMP v5.0",
-      "HMP v4.1",
-      "OpenCog Hyperon v0.6"
-    ]
-  }
-}
-```
-
-The `protocols` field is informational and non-binding.
-It does not imply full compliance with all listed specifications,
-but signals compatibility, partial support, or bridge capabilities.
-
-Nodes may use this information for:
-
-* protocol negotiation;
-* compatibility checks;
-* routing decisions;
-* selection of translators or bridge agents.
-
-This extension is optional and not required for HMP v5.0 compliance.
-
-##### Relation to Other `peer_announce` Extensions
-
-Several optional and descriptive extensions of `peer_announce` already explore directions related to competence, profile, and interoperability signaling, including:
-
-* declaration of supported internal formalisms and languages (`protocols`, see 12.8);
-* declaration of external or meta-protocol identities (`other_protocols`, see 12.11);
-* advertisement of external cognitive resources and container storage (`external`, see 12.12).
-
-These extensions are intentionally:
-
-* non-normative;
-* loosely structured;
-* declarative rather than prescriptive.
-
-They can be viewed as **early, experimental building blocks** toward future competence and profile containers, allowing real-world experimentation without freezing semantics prematurely.
+*Moved to Section 12 (Recommended Extensions).*
 
 ---
 
@@ -7116,196 +7310,13 @@ but does not interfere with how agents think, reason, or interpret received info
 
 ### 14.11 External Protocol Identifiers (`peer_announce.other_protocols`)
 
-This section proposes an optional extension to `peer_announce` that allows an agent to declare identifiers, roles, or capabilities associated with **external or meta-protocols**, without imposing any normative behavior on HMP nodes.
-
-The goal of this extension is to:
-
-* improve interoperability with other agent ecosystems (ANP, Agora, A2A, MCP, etc.);
-* enable protocol negotiation or delegation at higher layers;
-* allow agents to expose **multiple identities** across different protocol domains.
-
-This information is **purely declarative** and MAY be ignored by peers.
-
-#### Example
-
-```json
-{
-  "head": { "class": "peer_announce" },
-  "payload": {
-    "other_protocols": {
-      "ANP": {
-        "name": "Agent Network Protocol",
-        "source": "https://github.com/agent-network-protocol/AgentNetworkProtocol",
-        "agent_did": "did:anp:xyz123",
-        "public_key": "base64:ABCDEF...",
-        "roles": ["router", "translator"]
-      },
-      "Agora": {
-        "name": "Agora Protocol",
-        "roles": ["negotiator"],
-        "capabilities": ["protocol-selection", "schema-adaptation"]
-      }
-    }
-  }
-}
-```
-
-Notes:
-
-* No validation or handshake is required by HMP.
-* Roles and capabilities are advisory.
-* This extension complements existing `protocols`, `roles` and `capabilities` fields.
+*Moved to Section 12 (Recommended Extensions).*
 
 ---
 
 ### 14.12 External Resources and External Container Storage (`peer_announce.external`)
 
-This section proposes an optional mechanism for advertising **external cognitive resources**, including external container storage, mirrors, or rarely changing artifacts.
-
-The goal is to:
-- reduce unnecessary container transmission above the protocol;
-- allow static or large data to be accessed via standard transports (HTTP, FTP, magnet links, etc.);
-- support redundancy, mirroring, and trust-aware discovery;
-- the presence of an external resource reference does **not** imply availability, reachability, or trust.
-
-Use of external resources is **explicitly non-mandatory**.  
-Agents MAY choose to ignore these references entirely.
-
-#### Example
-```json
-{
-  "head": { "class": "peer_announce" },
-  "payload": {
-    "external": {
-      "https, main": {
-        "source": "https://example.org/",
-        "folders": {
-          "hmp/main": {
-            "hmp_container": true,
-            "title": "container_index and semantic_index",
-            "index": "index.json",
-            "types": ["json"]
-          },
-          "hmp/meta": {
-            "hmp_container": true,
-            "title": "Abstraction and axis containers",
-            "index": "index.json",
-            "types": ["json"]
-          },
-          "hmp/peer_announces": {
-            "hmp_container": true,
-            "title": "List of known HMP nodes",
-            "index": "index.json",
-            "types": ["json"]
-          },
-          "hmp/trust": {
-            "hmp_container": true,
-            "title": "Reputation containers",
-            "index": "index.json",
-            "types": ["json"]
-          },
-          "hmp/semantic": {
-            "hmp_container": true,
-            "title": "Semantic nodes and links",
-            "index": "index.json",
-            "types": ["json"]
-          },
-          ".well-known": {
-            "hmp_container": false,
-            "title": "Public agent descriptors (ANP, A2A, Agora, etc.)",
-            "index": "index.json",
-            "types": ["json"]
-          }
-        }
-      },
-      "ftp, work": {
-        "source": "ftp://example.org/",
-        "folders": {
-          "task": {
-            "hmp_container": true,
-            "title": "Current goals and tasks",
-            "types": ["json"]
-          },
-          "books/tech": {
-            "hmp_container": false,
-            "title": "Technical literature",
-            "types": ["txt", "md", "pdf"]
-          }
-        }
-      },
-      "magnet, archive": {
-        "source": "magnet:?xt=urn:btih:...",
-        "description": "Archived materials (legacy data)"
-      }
-    }
-  }
-}
-```
-
-Notes:
-- External resources may contain HMP containers or arbitrary files.
-- Authentication mechanisms are out of scope.
-- Trust, availability, and freshness are advisory hints only.
-- Implementations MAY use folder-level metadata (such as `hmp_container`) as a hint for indexing, caching, or deferred retrieval policies.
-- Keys such as `"https, main"` are illustrative, human-readable labels only; no naming scheme or key format is mandated by this specification.
-- The effective resource path is constructed by combining the `"source"` URI with the corresponding folder path. If an `"index"` field is present, it is interpreted as a relative path within that folder.
-- The `peer_announces` folder MAY contain cached or mirrored `peer_announce` containers of other agents, obtained via direct exchange, gossip, or trusted sources.
-
-#### Index Files (Optional)
-
-A folder entry in `peer_announce.external` MAY include an optional `"index"` field, which specifies a relative path to an index file located within that folder (e.g. `"index": "index.json"`).
-
-If present, the index file MAY be used by clients to:
-- discover files available in the folder;
-- obtain descriptive metadata (titles, timestamps, hashes);
-- selectively fetch or verify external resources.
-
-The structure and semantics of the index file are **not rigidly defined by HMP** and are provided as a **recommended, non-normative convention**.  
-Implementations are free to use alternative formats or schemas.
-
-**Example 1** (HMP container index)
-```json
-{
-  "path": "https://example.org/hmp/main",
-  "title": "container_index and semantic_index",
-  "files": {
-    "container_index.json": {
-      "description": "container_index from 2026-01-25 21:49",
-      "timestamp": "2026-01-25T21:49:00Z",
-      "hmp_container_class": "container_index",
-      "mime-type": "application/ld+json",
-      "hash": "sha256:abc123..."
-    },
-    "semantic_index.json": {
-      "description": "semantic_index from 2026-01-25 21:49",
-      "timestamp": "2026-01-25T21:49:00Z",
-      "hmp_container_class": "semantic_index",
-      "mime-type": "application/ld+json",
-      "hash": "sha256:abc123..."
-    }
-  }
-}
-```
-
-**Example 2** (Documentation / static files)
-```json
-{
-  "path": "https://github.com/kagvi13/HMP/blob/main/docs/",
-  "title": "HMP 5.0 Specification Documents",
-  "files": {
-    "Grok_HMP&ANP.md": {
-      "description": "Grok (xAI): comparative analysis of HMP and ANP (January 2026)",
-      "timestamp": "2026-01-22T08:46:00Z",
-      "mime-type": "text/markdown",
-      "hash": "sha256:abc123..."
-    }
-  }
-}
-```
-
-Updating an index file does **not** require reissuing `peer_announce`.  
-All fields in the index file are optional.  
-Clients MAY ignore the index entirely and interact with the external resource directly.
+*Moved to Section 12 (Recommended Extensions).*
 
 ---