// file: crates/knowledge-git-api/src/repository.rs
// version: 1

/// Provider-neutral operations required from a Git repository backend.
///
/// Implementations may use a local Git executable, a Rust Git library or another generic Git
/// mechanism. Forge-only capabilities do not belong to this trait.
pub trait GitRepository {
    /// Implementation-specific recoverable error.
    type Error;

    /// Refresh the local view of one configured source when the backend requires it.
    fn refresh(&mut self, source_id: &knowledge_domain_lib::SourceId) -> Result<(), Self::Error>;

    /// Resolve one opaque reference to the authoritative revision used by synchronization.
    fn resolve_revision(&self, source_id: &knowledge_domain_lib::SourceId, reference: &crate::GitReference) -> Result<crate::GitRevision, Self::Error>;

    /// Prepare or validate a read-only local snapshot for one resolved revision.
    fn prepare_snapshot(&self, source_id: &knowledge_domain_lib::SourceId, revision: &crate::GitRevision) -> Result<crate::GitSnapshot, Self::Error>;
}