queue

type AnswerRecord struct {
	// Ref is the question ref being answered. Required.
	Ref string
	// Answer is the owner's decision text. Required.
	Answer string
	// PapID is the PapDashboard question ID, for provenance. Optional.
	PapID string
	// AnsweredAt is when the answer was recorded on PapDashboard. Zero
	// means now.
	AnsweredAt time.Time
	// Question optionally carries the asked text (the PapDashboard body
	// carries it); when empty, RecordAnswer copies it from the matching
	// task.question-asked fact so the answered fact stays self-contained.
	Question string
}

type Band string

type Claim string

type EnqueueDetail struct {
	Project  string `json:"project,omitempty"`
	Type     string `json:"type,omitempty"`
	Priority *int   `json:"priority,omitempty"`
	DedupKey string `json:"dedup_key,omitempty"`
	// The task snapshot (plain enqueue only). Payload is the raw payload
	// bytes; NotBefore/CreatedAt are unix millis — the exact task-row
	// storage format, so a transition replay reconstructs the row
	// without precision loss. MaxAttempts is post-Normalize (never 0).
	Payload     string    `json:"payload"`
	Deps        []task.ID `json:"deps,omitempty"`
	MaxAttempts int       `json:"max_attempts,omitempty"`
	NotBefore   int64     `json:"not_before,omitempty"`
	CreatedAt   int64     `json:"created_at,omitempty"`
	Rescue      string    `json:"rescue,omitempty"`
}

type Filter struct {
	Project *string
	Status  *task.Status
	Type    *string
	// Query is a case-insensitive substring search over id, type, project,
	// payload, lease owner and last error — pushed into SQL LIKE, not a
	// post-filter.
	Query string
	// PayloadContains is a case-insensitive substring search over the
	// payload ALONE — pushed into SQL LIKE, so limit/offset semantics
	// survive the filter. `tq tasks --verify-contains` rides it:
	// stale-verify hygiene audits correlate the pinned verify string
	// across the matching set without a `tq show` per task (09-39 §e1).
	PayloadContains string
	// DedupKey is an exact-match filter over the dedup key — the
	// forensics pushdown behind `tq tasks --dedup`: which task (if any)
	// a dedup key resolved to, without a payload LIKE guess.
	DedupKey string
	Limit    int
	// Offset skips the first Offset matches (pagination); applied after
	// ordering. Meaningful together with Limit.
	Offset int
	// SeverityOrder orders by display severity (dead, running, pending,
	// cancelled, completed), newest first within a status — the dashboard
	// table order, stable across pages. Default order stays priority then
	// age (the queue's fairness order).
	SeverityOrder bool
	// Sort overrides the ordering with an allowlisted column sort for the
	// dashboard's sortable headers: "age-asc", "age-desc",
	// "priority-asc", "priority-desc", "attempts-asc", "attempts-desc".
	// Unknown values fall back to the default order (never interpolated
	// into SQL).
	Sort string
	// Since restricts the listing to tasks created at or after this time
	// (inclusive) — pushed into SQL as a created_at comparison, not a
	// post-filter.
	Since *time.Time
	// Parked restricts the listing to rate-limit-parked tasks: pending
	// with not_before in the future (the "11 tasks parked until 19:40"
	// one-glance view). false or nil leaves the filter off.
	Parked *bool
	// PriorityMin/PriorityMax bound the listing to a STORED-priority
	// range - the band filter's pushdown (hot = [100,149], machine =
	// [150,infinity)). nil leaves the bound open. Aging is scheduling,
	// not state: the range sees the stored value, not the effective rank.
	PriorityMin *int
	PriorityMax *int
}

type ParkedDetail struct {
	Reason  string `json:"reason,omitempty"`
	UntilMS int64  `json:"until_ms"`
	By      string `json:"by,omitempty"`
}

type PriorityScore struct {
	ItemKey       string `json:"itemKey"`
	Score         int    `json:"score"`         // 0-100 (clamped to the backlog band on use)
	EffortMinutes int    `json:"effortMinutes"` // estimated agent effort
	Source        string `json:"source"`        // scorer identity, e.g. "ai:<model>"
	Reasoning     string `json:"reasoning"`     // one-line why
	Tokens        int    `json:"tokens"`        // tokens the verdict cost
	ScoredAt      int64  `json:"scoredAt"`      // unix millis
}

type QuestionAnsweredDetail struct {
	Ref        string `json:"ref"`
	Question   string `json:"question,omitempty"`
	Answer     string `json:"answer"`
	PapID      string `json:"pap_id,omitempty"`
	AnsweredAt int64  `json:"answered_at,omitempty"`
}

type QuestionAskedDetail struct {
	Ref       string   `json:"ref"`
	Type      string   `json:"type"`
	Question  string   `json:"question"`
	Options   []string `json:"options,omitempty"`
	Repo      string   `json:"repo,omitempty"`
	ExpiresAt int64    `json:"expires_at,omitempty"`
}

type Queue struct {
	Store
}

type ReprioritizeEvidence struct {
	OldPriority int    `json:"old_priority"`
	NewPriority int    `json:"new_priority"`
	Source      string `json:"source"`
	Reason      string `json:"reason,omitempty"`
}

type RequeueEvidence struct {
	Reason         string `json:"reason"`
	RetryIn        int64  `json:"retry_in_ms"`
	ResumeCloseout bool   `json:"resume_closeout,omitempty"`
	Class          string `json:"class,omitempty"`
	Provider       string `json:"provider,omitempty"`
}

type Store interface {
	// Enqueue persists a new task (ID and defaults assigned here) and records
	// the task.enqueued fact.
	Enqueue(ctx context.Context, n task.New) (task.Task, error)
	// ClaimDue atomically claims at most one due task for owner: pending,
	// NotBefore passed, all deps completed. Sets Running + lease and mints
	// the claim token the caller must present on every finalize. Returns
	// ErrNoTaskDue when nothing is claimable.
	ClaimDue(ctx context.Context, owner string, lease time.Duration) (task.Task, Claim, error)
	// ClaimDueTypes is ClaimDue with an executor-type filter: only tasks
	// whose type is in types are candidates (nil or empty = any type). The
	// bare-worker refusal: a pool whose registry holds only sh never claims
	// an agent task — it stays PENDING for a pool that can run it, instead
	// of dead-lettering on a permanent unknown-type lookup error. No claim,
	// no task.claimed fact: the loop-suspect census stays clean.
	ClaimDueTypes(ctx context.Context, owner string, lease time.Duration, types []string) (task.Task, Claim, error)
	// Complete marks a Running task Completed (live claim required) and
	// records the task.completed fact.
	Complete(ctx context.Context, id task.ID, claim Claim, result jsontext.Value) error
	// Fail records a failed attempt. When attempts remain the task returns to
	// Pending with NotBefore = now + backoff(attempt); otherwise it is
	// Dead-lettered. Facts: task.failed (+ task.dead-lettered). evidence,
	// when non-empty (executor.FailureEvidence JSON), lands on the
	// task.failed fact's detail — the forensics (exit code, output tail)
	// that make a failed attempt debuggable from the journal alone.
	Fail(
		ctx context.Context,
		id task.ID,
		claim Claim,
		errText string,
		backoff time.Duration,
		evidence jsontext.Value,
	) error
	// FailPermanent dead-letters a Running task immediately, regardless of
	// the attempt budget: the error class makes retrying pointless. The
	// attempt is still counted. Facts: task.failed (carrying evidence)
	// + task.dead-lettered (class "permanent").
	FailPermanent(ctx context.Context, id task.ID, claim Claim, errText string, evidence jsontext.Value) error
	// Requeue returns a claimed task to Pending WITHOUT counting an
	// attempt; it becomes claimable again after delay. For preflight
	// refusals: the environment was not ready, not the task. A
	// rate-limited close-out passes resumeCloseout so the journal records
	// that the re-claim resumes the owed close-out turn instead of
	// re-running the paid work turn. class names the refusal family
	// (RequeueClass* constants) and rides the fact detail; empty is
	// written as absent and read back as RequeueClassUnknown. provider
	// (empty when the failing output named none) records WHICH provider
	// exhausted so the parked surface answers "which provider is
	// limited?" in one glance (04-03 §f8). Facts:
	// task.requeued.
	Requeue(
		ctx context.Context,
		id task.ID,
		claim Claim,
		errText string,
		delay time.Duration,
		resumeCloseout bool,
		class string,
		provider string,
	) error
	// UpdatePendingPriority changes a PENDING task's priority (ADR-0015
	// §5) and records the task.reprioritized fact (old/new, source,
	// reason) in the SAME transaction. Running/terminal tasks are refused
	// with task.ErrInvalidTransition — priority is enqueue-time truth for
	// anything already claimed or finished. A same-value update is a
	// no-op: no error, no fact (idempotency: reruns and racing sweepers
	// never spam the journal).
	UpdatePendingPriority(ctx context.Context, id task.ID, newPriority int, source, reason string) error
	// Park suppresses claims on a PENDING task until the given instant
	// (tq park): NotBefore moves to until (clamped to now) and the
	// task.parked fact records reason and by, in the SAME transaction. No
	// attempt burns; expiry — or parking with a past until, the release —
	// re-arms claims. Running/terminal tasks are refused with
	// task.ErrInvalidTransition, unknown ids with task.ErrNotFound.
	// Operator rulings are history: every call appends its fact.
	Park(ctx context.Context, id task.ID, reason string, until time.Time, by string) error
	// RecordAnswer records an owner's decision for a parked task's
	// question (PapDashboard questions): appends task.question-answered
	// and — when the task is PENDING — injects the answer into the task's
	// JSON-object payload under the "answered" key and clears NotBefore,
	// all in the SAME transaction, so the next claim runs knowing the
	// decision and "answered but still parked" is unrepresentable.
	// Idempotent per question ref: a replayed record appends nothing and
	// mutates nothing. A task in any other state (running, terminal)
	// records the fact only — the journal keeps the ruling, a live or
	// finished task cannot use it. Non-object payloads get the fact only
	// too: answers cannot be merged into a raw-text payload.
	RecordAnswer(ctx context.Context, id task.ID, ans AnswerRecord) error
	// Heartbeat extends the lease of a Running task held by the claim.
	Heartbeat(ctx context.Context, id task.ID, claim Claim, extend time.Duration) error
	// Cancel withdraws a Pending task. A non-empty reason is stored in the
	// task.cancelled fact's detail ("reason" key) so the journal records WHY
	// the task was withdrawn.
	Cancel(ctx context.Context, id task.ID, reason string) error
	// CancelRunning records a cooperative cancel request for a Running
	// task: the task.cancel-requested fact is the flag. The executing
	// worker observes it at its next heartbeat, stops the execution, and
	// finalizes with CancelOwned; an expired lease finalizes it at
	// reclaim. A non-empty reason is stored on the request fact's detail
	// and carried onto the final task.cancelled fact. Idempotent — a
	// second request appends nothing.
	CancelRunning(ctx context.Context, id task.ID, reason string) error
	// CancelRequested reports whether a cooperative cancel request is
	// pending for the task — the worker's heartbeat observation query.
	CancelRequested(ctx context.Context, id task.ID) (bool, error)
	// CancelOwned finalizes a cooperative cancel: Running -> Cancelled,
	// recorded by the lease-holding worker after it stopped the execution.
	// The claim must still be the task's lease token, but the lease MAY
	// have lapsed: a worker legitimately finishes the stop just after
	// expiry but before a reclaim.
	CancelOwned(ctx context.Context, id task.ID, claim Claim) error
	// MarkOrphaned appends a task.orphaned fact for every Running task
	// whose lease expired before the cutoff and that has no orphaned fact
	// yet (idempotent). It changes no state — orphans stay Running until a
	// reclaim — it records WHY the task is stranded so the journal can
	// explain it. Returns how many facts were appended.
	MarkOrphaned(ctx context.Context, cutoff time.Time) (int, error)
	// RescueDead re-queues a Dead task with a fresh attempt budget.
	RescueDead(ctx context.Context, id task.ID, maxAttempts int) error
	// DismissDead cancels a Dead task with a recorded reason (DLQ dismiss):
	// the autopsy verdict "unfixable" or an operator's ruling. The
	// task.cancelled fact's detail carries the reason and who dismissed it,
	// so the journal keeps the full death evidence plus the WHY of the
	// withdrawal. Dead is terminal otherwise; facts are never deleted.
	DismissDead(ctx context.Context, id task.ID, reason, by string) error
	// Get returns the current task record.
	Get(ctx context.Context, id task.ID) (task.Task, error)
	// List returns tasks matching the filter.
	List(ctx context.Context, f Filter) ([]task.Task, error)
	// Facts exposes the journal (same store, same transaction domain):
	// facts with Seq strictly greater than after, in Seq order. limit
	// bounds the result when > 0; 0 means unbounded (bulk exports).
	Facts(ctx context.Context, after int64, limit int) ([]journal.Fact, error)
	// LastFacts returns the most recent limit facts in ascending Seq
	// order — the bounded read behind feed-style renders. limit <= 0
	// returns the whole journal.
	LastFacts(ctx context.Context, limit int) ([]journal.Fact, error)
	// HeadSeq returns the current highest fact Seq (0 when the journal is
	// empty): the O(1) watermark for tailers, bridges and resume points.
	HeadSeq(ctx context.Context) (int64, error)
	// Watermark returns the persisted read cursor for a journal consumer
	// and whether the consumer ever checkpointed (seq 0 is a valid cursor:
	// "consumed nothing yet"): the resume point for bridges and sweepers
	// after a restart.
	Watermark(ctx context.Context, consumer string) (seq int64, exists bool, err error)
	// SaveWatermark checkpoints a consumer cursor as a monotonic upsert
	// (never regresses). It records consumer progress, not task state, so
	// no fact is appended.
	SaveWatermark(ctx context.Context, consumer string, seq int64) error
	// SavePriorityScore upserts one cached item score (ADR-0015 score
	// cache): an AI verdict persists and re-derives the same priority
	// until the item text changes and re-keys. No fact — the cache is a
	// projection input, not queue history.
	SavePriorityScore(ctx context.Context, score PriorityScore) error
	// PriorityScore returns the cached verdict for an item key, if any.
	PriorityScore(ctx context.Context, itemKey string) (PriorityScore, bool, error)
	// PriorityScores returns every cached verdict (ADR-0015 score cache),
	// ordered by item key — the scan domain of the score-cache prune
	// pass. The cache stays small by construction (one row per scored
	// item key), so the read is unbounded by design.
	PriorityScores(ctx context.Context) ([]PriorityScore, error)
	// DeletePriorityScores removes the cached verdicts for the given item
	// keys — the score-cache prune half: a reworded or vanished item
	// leaves its old key's verdict orphaned forever unless evicted.
	// Unknown keys are not an error; an empty key list deletes nothing.
	// Returns how many rows went away.
	DeletePriorityScores(ctx context.Context, itemKeys []string) (int64, error)
	// FactsForTask returns one task's facts in Seq order, bounded to the
	// most recent limit when > 0 (0 = unbounded).
	FactsForTask(ctx context.Context, id string, limit int) ([]journal.Fact, error)
	// ClaimCounts counts task.claimed facts per task id in one GROUP BY —
	// the census pushdown behind loop-suspect detection
	// (ClaimAnomalyThreshold): one grouped read instead of a facts walk
	// per task.
	ClaimCounts(ctx context.Context) (map[string]int, error)
	// CountFacts counts facts of one type recorded at or after since —
	// the SQL pushdown behind spend projections and stats.
	CountFacts(ctx context.Context, ftype journal.FactType, since time.Time) (int64, error)
	// FactsSince returns the facts of one type recorded at or after
	// since, in Seq order — the read sibling of CountFacts for
	// projections that must sum over the matching facts' detail (budget
	// session-usage projection) rather than only count them. limit bounds
	// the result when > 0; 0 means unbounded.
	FactsSince(ctx context.Context, ftype journal.FactType, since time.Time, limit int) ([]journal.Fact, error)
	// StatusCounts counts tasks per status — the GROUP BY behind dashboard
	// counters: O(statuses) work instead of a full task scan.
	StatusCounts(ctx context.Context) (map[task.Status]int, error)
	// ProjectCounts counts tasks per project per status — the GROUP BY
	// behind the overview chips and per-project views.
	ProjectCounts(ctx context.Context) (map[string]map[task.Status]int, error)
	// CountTasks counts the tasks matching the filter — the COUNT(*)
	// pushdown behind pagination ("page 2 of 14").
	CountTasks(ctx context.Context, f Filter) (int, error)
	// Close releases resources.
	Close() error
}

type UnblockChange struct {
	TaskID        task.ID `json:"task_id"`
	OldPriority   int     `json:"old_priority"`
	NewPriority   int     `json:"new_priority"`
	CompletedDeps int     `json:"completed_deps"`
}

type Waker interface {
	// Notify yields the claim-wake channel. It fires after any commit
	// that may have landed a task in PENDING (enqueue, requeue, fail with
	// retries remaining, rescue, a parked question answered).
	Notify() <-chan struct{}
}

type WatermarkEntry struct {
	Consumer  string
	Seq       int64
	UpdatedAt int64 // unix millis
}