claim

type Claim struct {
	Scope       string
	ID          string
	Holder      string
	LeaseUntil  libtime.DateTime
	RenewBefore libtime.DateTime
	LeaseToken  string
}

type ClaimClient interface {
	// Acquire takes the claim for holder with the given TTL in seconds. A held
	// claim returns a *ClaimHeldError. An expired lease is taken over, so a
	// dead holder cannot block the target forever.
	Acquire(ctx context.Context, target ClaimTarget, holder string, ttlSeconds int) (*Claim, error)
	// Renew extends an existing lease. It never takes over: a stale token
	// returns ErrLeaseLost and the caller re-acquires.
	Renew(
		ctx context.Context,
		target ClaimTarget,
		leaseToken string,
		ttlSeconds int,
	) (*Claim, error)
	// Release drops the claim. A token that is no longer current is
	// ErrLeaseLost, not a silent success.
	Release(ctx context.Context, target ClaimTarget, leaseToken string) error
	// Read returns the current claim, or ErrClaimFree when there is none.
	Read(ctx context.Context, target ClaimTarget) (*Claim, error)
}

type ClaimHeldError struct {
	Holder     string
	LeaseUntil libtime.DateTime
}

type ClaimRef struct {
	Ref        string `json:"ref"`
	Sha        string `json:"sha"`
	Cluster    string `json:"cluster"`
	TaskID     string `json:"task_id"`
	LeaseUntil string `json:"lease_until"`
}

type ClaimRefClient interface {
	// List returns every claim ref whose path is prefix or lies under it as a
	// whole path component. prefix is passed as the ?prefix= query value.
	List(ctx context.Context, prefix string) ([]ClaimRef, error)
	// Put creates or replaces the claim at key by compare-and-swap. An empty
	// expectedSha means "must not exist". It returns the new sha from the
	// server response. A 409 is ErrLeaseConflict.
	Put(
		ctx context.Context,
		key string,
		expectedSha string,
		cluster string,
		taskID string,
		leaseUntil libtime.DateTime,
	) (string, error)
	// Delete removes the claim at key by compare-and-swap. A 409 is
	// ErrLeaseConflict.
	Delete(ctx context.Context, key string, expectedSha string) error
}

type ClaimTarget struct {
	// TaskID addresses a task claim. Mutually exclusive with Owner/Repo.
	TaskID string
	// Owner and Repo address a repository claim.
	Owner string
	Repo  string
}

type HeldClaim struct {
	Key        string
	TaskID     string
	Sha        string
	LeaseUntil libtime.DateTime
}

type JobControl interface {
	// IsJobRunning reports whether a non-terminal Job exists for taskID.
	IsJobRunning(ctx context.Context, taskID string) (bool, error)
	// DeleteJob deletes the Job for taskID. Deleting an absent Job is not an
	// error (idempotent).
	DeleteJob(ctx context.Context, taskID string) error
}

type LeaseManager interface {
	Claim(ctx context.Context, key string, taskID string) (*HeldClaim, error)
	// ClaimPair creates both refs of a claim. The primary is written first; the
	// secondary is written only when it is non-empty. The claim is held only
	// when every write succeeded, or when a failed primary write was read back
	// as this manager's own. A secondary conflict releases the primary and
	// returns ErrLeaseConflict.
	ClaimPair(
		ctx context.Context,
		primary string,
		secondary string,
		taskID string,
	) (*HeldClaim, error)
	Release(ctx context.Context, key string) error
	// ReleaseAfterSuccess releases the claim like Release, but not before
	// SuccessGracePeriod has elapsed since completedAt. Until then the claim
	// stays held and keeps being renewed, so a peer cluster's Claim gets a 409
	// instead of a task another cluster has already run.
	ReleaseAfterSuccess(ctx context.Context, key string, completedAt libtime.DateTime) error
	Takeover(ctx context.Context, key string, taskID string) (*TakeoverResult, error)
	// TakeoverPair is Takeover over both refs of a claim. An empty secondary
	// behaves exactly like Takeover.
	TakeoverPair(
		ctx context.Context,
		primary string,
		secondary string,
		taskID string,
	) (*TakeoverResult, error)
	Tick(ctx context.Context) error
	Run(ctx context.Context) error
	Recover(ctx context.Context) error
	// HeldClaims returns a snapshot sorted by Key. Claims in pending Job
	// deletion or pending release are included: they are still held until the
	// pending action completes or the fence drops them.
	HeldClaims() []HeldClaim
	// AuditMismatch compares the claims this manager holds with the given set of
	// running Job task ids. It adds 1 to executor_claim_mismatch_total for every
	// running Job with no held claim and for every held claim with no running
	// Job, and logs which case each was. A task present in both is not counted.
	AuditMismatch(ctx context.Context, runningTaskIDs map[string]bool)
}

type RedriveReasonStore interface {
	// Record appends one failure reason for taskID at phase. An empty reason is
	// recorded as RedriveReasonUnknown. Recording at a new phase deletes the
	// task's refs at every other phase, exactly as the streak store does.
	Record(ctx context.Context, taskID string, phase string, reason string) error
	// Reasons returns one element per ref at (taskID, phase), ordered by the
	// numeric suffix ascending. The order is load-bearing: the classifier reads
	// only the most recent count entries, so a reason left behind by an earlier
	// streak cannot skew the class.
	Reasons(ctx context.Context, taskID string, phase string) ([]string, error)
	// Snapshot returns every parsed reason ref as taskID → phase component →
	// reasons, from ONE list call over the whole reason prefix, each slice
	// ordered exactly as Reasons returns it. The reconcile pass feeds the same
	// classifier, so the two must agree on order.
	Snapshot(ctx context.Context) (map[string]map[string][]string, error)
	// Clear removes every reason ref of taskID, at every phase.
	Clear(ctx context.Context, taskID string) error
}

type RedriveStreakStore interface {
	// Count returns how many streak refs taskID has at phase. Refs at other
	// phases and refs whose key does not parse are not counted.
	Count(ctx context.Context, taskID string, phase string) (int, error)
	// Snapshot returns every parsed streak ref as taskID → phase component →
	// count, from ONE list call over the whole streak prefix. The reconcile pass
	// reads it once and answers every candidate's cap check from the result;
	// Count issues one list per task, which is what put a pass over a large
	// candidate set over its budget (see handler/redrive_streak_cache.go).
	// Keys are normalized with RedriveStreakPhaseComponent.
	Snapshot(ctx context.Context) (map[string]map[string]int, error)
	// Record appends one spawn of taskID at phase, then deletes the task's
	// refs at every other phase. A 409 create is retried on the next free
	// number at most redriveStreakMaxCreateAttempts times.
	Record(ctx context.Context, taskID string, phase string) error
	// Clear removes every parsed streak ref of taskID, at every phase.
	Clear(ctx context.Context, taskID string) error
}

type StatusError struct {
	Action string
	Target string
	Status int
}

type TakeoverResult struct {
	Key            string
	TaskID         string
	Sha            string
	LeaseUntil     libtime.DateTime
	PreviousTaskID string
}