// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

/**
 * @title RepositoryInterface
 * @dev Defines the core interface for repository interactions in the Source Weaver research ecosystem
 * @notice Provides a standardized contract for repository management and exploration
 */
interface RepositoryInterface {
    /// @dev Struct representing a repository entry/record
    struct RepositoryEntry {
        address owner;
        bytes32 contentHash;
        uint256 createdAt;
        uint256 lastUpdated;
        bool isActive;
        string metadata;
    }

    /// @dev Enum for repository access levels
    enum AccessLevel {
        PRIVATE,
        SHARED,
        PUBLIC
    }

    /// @dev Events for repository lifecycle and interactions
    event RepositoryCreated(
        bytes32 indexed repositoryId, 
        address indexed creator, 
        AccessLevel accessLevel
    );

    event RepositoryUpdated(
        bytes32 indexed repositoryId, 
        bytes32 newContentHash, 
        uint256 timestamp
    );

    event EntryAdded(
        bytes32 indexed repositoryId, 
        bytes32 indexed entryId, 
        address contributor
    );

    /// @notice Create a new repository
    /// @param name Repository name
    /// @param description Repository description
    /// @param accessLevel Visibility and access control level
    /// @return repositoryId Unique identifier for the created repository
    function createRepository(
        string memory name, 
        string memory description, 
        AccessLevel accessLevel
    ) external returns (bytes32 repositoryId);

    /// @notice Add an entry to an existing repository
    /// @param repositoryId Target repository identifier
    /// @param contentHash Hash representing the content being added
    /// @param metadata Additional metadata for the entry
    /// @return entryId Unique identifier for the added entry
    function addRepositoryEntry(
        bytes32 repositoryId, 
        bytes32 contentHash, 
        string memory metadata
    ) external returns (bytes32 entryId);

    /// @notice Update an existing repository entry
    /// @param repositoryId Repository containing the entry
    /// @param entryId Specific entry to update
    /// @param newContentHash Updated content hash
    /// @param newMetadata Updated metadata
    function updateRepositoryEntry(
        bytes32 repositoryId, 
        bytes32 entryId, 
        bytes32 newContentHash, 
        string memory newMetadata
    ) external;

    /// @notice Retrieve a specific repository entry
    /// @param repositoryId Repository containing the entry
    /// @param entryId Specific entry to retrieve
    /// @return entry The full repository entry details
    function getRepositoryEntry(
        bytes32 repositoryId, 
        bytes32 entryId
    ) external view returns (RepositoryEntry memory entry);

    /// @notice Check if a user has permission to modify a repository
    /// @param repositoryId Repository to check
    /// @param user Address to validate permissions
    /// @return hasPermission Boolean indicating access rights
    function hasRepositoryPermission(
        bytes32 repositoryId, 
        address user
    ) external view returns (bool hasPermission);

    /// @notice Get total number of entries in a repository
    /// @param repositoryId Repository to query
    /// @return entryCount Total number of entries
    function getRepositoryEntryCount(
        bytes32 repositoryId
    ) external view returns (uint256 entryCount);
}