// -----------------------------------------------------------------------------
// IArtifactIndexRepository.cs
// Sprint: SPRINT_20260118_017_Evidence_artifact_store_unification
// Task: AS-003 - Create ArtifactStore PostgreSQL index
// Description: Artifact index repository abstraction
// -----------------------------------------------------------------------------
using StellaOps.Artifact.Core;

namespace StellaOps.Artifact.Infrastructure;

/// <summary>
/// PostgreSQL repository for artifact index.
/// Provides efficient bom-ref based querying.
/// </summary>
public interface IArtifactIndexRepository
{
    /// <summary>
    /// Indexes a stored artifact.
    /// </summary>
    Task IndexAsync(ArtifactIndexEntry entry, CancellationToken ct = default);

    /// <summary>
    /// Finds artifacts by bom-ref.
    /// </summary>
    Task<IReadOnlyList<ArtifactIndexEntry>> FindByBomRefAsync(string bomRef, CancellationToken ct = default);

    /// <summary>
    /// Finds artifacts by bom-ref and serial number.
    /// </summary>
    Task<IReadOnlyList<ArtifactIndexEntry>> FindByBomRefAndSerialAsync(
        string bomRef,
        string serialNumber,
        CancellationToken ct = default);

    /// <summary>
    /// Gets a specific artifact index entry.
    /// </summary>
    Task<ArtifactIndexEntry?> GetAsync(
        string bomRef,
        string serialNumber,
        string artifactId,
        CancellationToken ct = default);

    /// <summary>
    /// Removes an artifact from the index.
    /// </summary>
    Task<bool> RemoveAsync(
        string bomRef,
        string serialNumber,
        string artifactId,
        CancellationToken ct = default);

    /// <summary>
    /// Finds artifacts by SHA-256 hash.
    /// </summary>
    Task<IReadOnlyList<ArtifactIndexEntry>> FindBySha256Async(string sha256, CancellationToken ct = default);

    /// <summary>
    /// Finds artifacts by type.
    /// </summary>
    Task<IReadOnlyList<ArtifactIndexEntry>> FindByTypeAsync(
        ArtifactType type,
        Guid tenantId,
        int limit = 100,
        CancellationToken ct = default);
}