TAMV Agent (Rust)

Relevant source files

The following files were used as context for generating this wiki page:

• tamv-agent/src/main.rs
• tamv-agent/src/protocol.rs
• tamv-agent/src/security.rs
• tamv-agent/Cargo.toml
• tamv-agent/README.md

The TAMV Agent is a standalone binary written in Rust designed to operate within the TAMV (Territorio Autónomo de Memoria Viva) mesh network. It functions as a cloud-independent node capable of maintaining local state, executing secure communication protocols, and participating in anti-entropy gossip cycles to ensure data consistency across the federated network.

The agent is built for resilience and local sovereignty, utilizing an asynchronous runtime to handle concurrent tasks such as heartbeats, message reception, and state synchronization. It serves as the primary bridge between physical mesh transport (like Wi-Fi or BLE) and the higher-level TAMV protocols.

Sources: tamv-agent/README.md, tamv-agent/src/main.rs

Core Architecture

The TAMV Agent architecture is centered around a continuous asynchronous loop powered by the tokio runtime. It maintains a strictly local state persisted as state.json and operates based on a config.toml file that defines node-specific parameters while maintaining protocol homogeneity.

Execution Flow

The agent follows a reactive pattern where it listens for incoming messages, validates them using HMAC signatures, and updates its local state or triggers chain-specific logic based on the message type.

The diagram shows the lifecycle of the TAMV Agent from initialization to the main operational loop.
Sources: tamv-agent/README.md, tamv-agent/src/main.rs

Protocol and Messaging

The agent utilizes a structured messaging system for inter-node communication. Messages are wrapped in a secure envelope and typed to distinguish between discovery, synchronization, and operational reports.

Message Types

Type	Description
HELLO	Initial node discovery and handshake.
STATE_SYNC	Exchange of local state for anti-entropy reconciliation.
CHAIN_STEP	Progression signal for the 1→206→1 chain protocol.
CHAIN_REPORT	Status reporting of chain completion or error states.

Sources: tamv-agent/README.md, tamv-agent/src/protocol.rs

Protocol Sequencing

The following sequence illustrates the typical synchronization flow between two nodes in the TAMV mesh.

This diagram depicts the discovery and state synchronization process between peer nodes.
Sources: tamv-agent/src/protocol.rs, tamv-agent/src/main.rs

Security and Persistence

Security is handled via a signature layer that ensures message integrity and authenticity without relying on a central authority.

HMAC Signature Layer

Every message transmitted by the TAMV Agent is signed using HMAC-SHA256. The security module is responsible for:

1. Generating unique nonces for each message to prevent replay attacks.
2. Computing signatures based on the shared federation key defined in config.toml.
3. Validating incoming signatures before processing payloads.

Sources: tamv-agent/src/security.rs, tamv-agent/Cargo.toml:9-12

Atomic Persistence

To prevent data corruption during power loss (common in edge deployments), the agent implements atomic persistence for state.json. When the internal state changes, the agent writes to a temporary file before renaming it to the target path, ensuring the local database remains consistent.

Sources: tamv-agent/README.md, tamv-agent/src/main.rs

Dependencies and Environment

The agent's implementation relies on a specific set of Rust crates to handle asynchrony, serialization, and cryptography.

Crate	Purpose
tokio	Asynchronous runtime for networking and timers.
serde / serde_json	Serialization of state and messages.
hmac / sha2	Cryptographic signatures for secure communication.
toml	Configuration parsing for config.toml.
chrono	Timestamping for logs and state versioning.

Sources: tamv-agent/Cargo.toml:5-15

Summary

The TAMV Agent (Rust) provides the foundational layer for a sovereign, decentralized territory. By prioritizing local persistence, secure gossip protocols, and cloud-independent operation, it enables a resilient digital twin of the physical territory that can withstand external infrastructure failures.

Sources: tamv-agent/README.md, tamv-agent/src/main.rs