// SPDX-License-Identifier: MIT
pragma solidity 0.8.23;

/**
 * @title IERC8004, the ERC-8004 "Trustless Agents" registry surface AS MODELED for Aere Network
 *
 * @notice ERC-8004 defines three on-chain registries that give autonomous / AI agents a
 *         portable, verifiable trust layer on top of the A2A (Agent-to-Agent) protocol:
 *           - IDENTITY   : a unique on-chain agent id resolving to an off-chain AgentCard
 *                          (a metadata document, e.g. "/.well-known/agent-card.json").
 *           - REPUTATION : client feedback / attestations about an agent, readable on-chain.
 *           - VALIDATION : independent validators requesting and responding to proofs about
 *                          an agent's work.
 *
 *         These interfaces capture the DOCUMENTED request / resolve / attest / validate
 *         SEMANTICS of ERC-8004 so Aere's already-deployed agent primitives can expose a
 *         standards-shaped surface over them.
 *
 * @dev    [VERIFY: confirm against the finalized ERC-8004 interface]
 *         ERC-8004 is a live, evolving draft. Between draft revisions the Identity registry
 *         has moved toward an ERC-721 registration model (register / tokenURI), and the
 *         Reputation and Validation function names and argument orders are still settling.
 *         The shapes below are the semantic model the Aere adapters implement; the exact
 *         function selectors and event topics MUST be reconciled with the final ERC text
 *         before any byte-level selector-conformance claim is made. Where the model departs
 *         from a specific draft, the adapter NatSpec says so.
 */

/// @notice ERC-8004 Identity registry: register / resolve an agent with a DID + metadata URI.
interface IERC8004Identity {
    struct AgentInfo {
        uint256 agentId; // the ERC-8004 agent id
        string did; // decentralized identifier, e.g. "did:aere:2800:<agentId>"
        string agentDomain; // the agent's domain, e.g. "agent.example.com"
        string agentCardURI; // AgentCard / registration metadata document URI
        address agentAddress; // the address that controls / acts as the agent
        bool registered; // whether ERC-8004 metadata has been bound for this agent
    }

    event AgentRegistered(
        uint256 indexed agentId, string agentDomain, string agentCardURI, address indexed agentAddress
    );
    event AgentUpdated(
        uint256 indexed agentId, string agentDomain, string agentCardURI, address indexed agentAddress
    );

    function getAgent(uint256 agentId) external view returns (AgentInfo memory);
    function resolveByDomain(string calldata agentDomain) external view returns (AgentInfo memory);
    function resolveByAddress(address agentAddress) external view returns (AgentInfo memory);
    function agentCount() external view returns (uint256);
}

/// @notice ERC-8004 Reputation registry: attest / read feedback about an agent.
interface IERC8004Reputation {
    /// @param delta the feedback signal, normalized to {-1, 0, +1}: +1 positive, -1 dispute, 0 neutral.
    event NewFeedback(
        uint256 indexed agentId, address indexed attestor, int8 delta, bytes32 evidenceHash, string evidenceURI
    );

    function giveFeedback(uint256 agentId, int8 delta, bytes32 evidenceHash, string calldata evidenceURI) external;
    function getScore(uint256 agentId) external view returns (uint256);
}

/// @notice ERC-8004 Validation registry: request / respond with a proof.
interface IERC8004Validation {
    enum Status {
        None, // no such request
        Pending, // requested, awaiting a validator response
        Completed // validator responded with a proof

    }

    event ValidationRequest(
        bytes32 indexed requestId, uint256 indexed validatorKeyId, uint256 indexed serverAgentId, bytes32 dataHash
    );
    event ValidationResponse(
        bytes32 indexed requestId,
        uint256 indexed validatorKeyId,
        uint256 indexed serverAgentId,
        uint8 response,
        uint8 pqcScheme
    );

    function requestValidation(uint256 validatorKeyId, uint256 serverAgentId, bytes32 dataHash)
        external
        returns (bytes32 requestId);
    function respondValidation(bytes32 requestId, uint8 response, bytes calldata pqcProof) external;
}