namespace ClawdDotNet.Core.Tasks;

/// <summary>
/// Der Ausführungszustand des Taskboards. Die Definition der Aufgaben lebt in
/// Markdown-Dateien; dieses Repository ist die DB-Seite, die das Claiming atomar macht
/// (was ein Dateisystem nicht verlässlich kann) und dem Scanner erlaubt, ohne
/// Dateizugriff zu entscheiden.
/// </summary>
public interface ITaskRepository
{
    /// <summary>
    /// Legt eine Aufgabe an oder aktualisiert ihre Definition (Importer). Idempotent über
    /// die <see cref="TaskItem.Id"/> — ein zweiter Import erzeugt keine Dublette. Der
    /// Ausführungszustand (Marker, Claim) bleibt dabei unangetastet.
    /// </summary>
    Task<TaskItem> UpsertAsync(TaskItem task, CancellationToken ct);

    Task<TaskItem?> GetAsync(string id, CancellationToken ct);

    Task<IReadOnlyList<TaskItem>> ListAsync(TaskQuery query, CancellationToken ct);

    /// <summary>
    /// Beansprucht einen fälligen Termin atomar. Genau ein gleichzeitiger Aufruf gewinnt;
    /// jeder weitere erhält <c>false</c>. Setzt den Marker (<paramref name="occurrenceKey"/>)
    /// sofort — ein Termin ist damit auch dann verbraucht, wenn der Lauf später scheitert
    /// oder der Prozess abstürzt (at-most-once, kein Retry-Sturm).
    /// </summary>
    /// <param name="occurrenceKey">Sortierbarer ISO-UTC-Zeitstempel des Termins.</param>
    /// <param name="leaseCutoff">
    /// Claims, die älter sind, gelten als verwaist (abgestürzter Lauf) und dürfen
    /// überschrieben werden.
    /// </param>
    Task<bool> TryClaimAsync(
        string id, string occurrenceKey, string claimToken,
        DateTime now, DateTime leaseCutoff, CancellationToken ct);

    /// <summary>
    /// Schließt einen beanspruchten Lauf ab und setzt den Endstatus. Nur wirksam, solange
    /// der Aufrufer den Claim noch hält (<paramref name="claimToken"/> passt) — ein Lauf,
    /// der seine Lease verloren hat, überschreibt nichts mehr. Gibt zurück, ob der Claim
    /// noch gehörte.
    /// </summary>
    Task<bool> CompleteClaimAsync(
        string id, string claimToken, TaskItemStatus finalStatus,
        DateTime now, CancellationToken ct);

    /// <summary>Ändert den Status direkt (Tool-Aktionen, Auto-Dispatch, Eskalation).</summary>
    Task<bool> SetStatusAsync(string id, TaskItemStatus status, DateTime now, CancellationToken ct);

    /// <summary>
    /// Reconciliation beim Start: verwaiste Claims (älter als <paramref name="leaseCutoff"/>)
    /// lösen und die betroffenen Aufgaben von <see cref="TaskItemStatus.InProgress"/> zurück
    /// auf <see cref="TaskItemStatus.Todo"/> stellen. Gibt die Zahl der zurückgesetzten
    /// Aufgaben zurück.
    /// </summary>
    Task<int> ReleaseStaleClaimsAsync(DateTime leaseCutoff, DateTime now, CancellationToken ct);

    /// <summary>
    /// Aufgaben, die auf <paramref name="blockerId"/> warten — Grundlage für den
    /// Auto-Dispatch, wenn der letzte Blocker fertig wird.
    /// </summary>
    Task<IReadOnlyList<TaskItem>> ListBlockedByAsync(string blockerId, CancellationToken ct);

    Task<int> CountAsync(CancellationToken ct);
}
