board

type AcceptanceCriterion struct {
	Text string `json:"text"`
	Met  bool   `json:"met"`
}

type Actor struct {
	// Kind is "user" or "system" (the reconciler is a system actor,
	// exempt from the claim-token guard by construction).
	Kind string
	// UserID is the acting user (workers delegate as the owning user,
	// ruling R7; empty for system actors).
	UserID string
	// Surface is the projection the action arrived on.
	Surface string
	// ClaimToken is the in-flight guard on caller surfaces (empty for
	// the reconciler, cancel, and manager pending_input exits — the two
	// named caller-side overrides).
	ClaimToken string
	// WorkspaceID is the resolved pod workspace on the agent surface
	// (design §4.4 caller-workspace binding, structural: an in-workspace
	// worker may only touch tasks whose project targets ITS workspace).
	// Empty on manager surfaces (REST/external MCP scope by ownership).
	WorkspaceID string
}

type Claim struct {
	TaskID         string    `json:"task_id"`
	ShortID        string    `json:"short_id"`
	ProjectID      string    `json:"project_id"`
	EpicID         string    `json:"epic_id"`
	WorkspaceID    string    `json:"workspace_id"`          // the project's target — the spawn's destination (R9)
	ClaimToken     string    `json:"claim_token,omitempty"` // empty on escalation (grant withheld)
	Assignee       string    `json:"assignee,omitempty"`
	LeaseExpiresAt time.Time `json:"lease_expires_at,omitempty"` // zero on escalation
	// Escalated is true when the grant was withheld: the task's
	// pre-increment attempts >= N and it was staged to pending_input
	// (origin escalated) instead. The caller claims the next candidate.
	Escalated bool  `json:"escalated"`
	Task      *Task `json:"task,omitempty"`
}

type Clock func() time.Time

type DependencyError struct {
	Code        string // "cycle" | "cross_project" | "self"
	Detail      string
	Suggestions []string
}

type DuplicateError struct {
	EventID string
	Action  string
	Result  map[string]any
}

type EngineConfig struct {
	// AttemptsCap is N — the attempts ceiling. The (N+1)th claim attempt
	// (pre-increment attempts >= N) escalates to pending_input instead of
	// granting. Default 3.
	AttemptsCap int
	// LeaseDuration is how long a claim holds without progress evidence
	// (#1685 semantics: elapsed time is not liveness). Default 15m.
	LeaseDuration time.Duration
	// ThrottleBackoff is the cooldown applied by report_throttle to both
	// the task (cooldown_until) and the project (slot_cooldown_until).
	// Default 5m.
	ThrottleBackoff time.Duration
	// DRRQuantum is the default per-epic deficit-round-robin round
	// allowance (epics.quantum). Default 1.
	DRRQuantum int
	// SweepInterval is the reconciler cadence (advisory for the sweep
	// runner; the sweep itself is stateless). Default 30s.
	SweepInterval time.Duration
}

type Epic struct {
	ID          string    `json:"id"`
	ProjectID   string    `json:"project_id"`
	ShortID     string    `json:"short_id"`
	Title       string    `json:"title"`
	Outcome     string    `json:"outcome"`
	Status      string    `json:"status"`
	Priority    string    `json:"priority"`
	ProjectName string    `json:"project_name"`
	Tags        []string  `json:"tags"`
	VFT         int64     `json:"vft"`
	Deficit     int64     `json:"deficit"`
	Quantum     int       `json:"quantum"`
	CreatedAt   time.Time `json:"created_at"`
	UpdatedAt   time.Time `json:"updated_at"`
	// Derived progress (ruling R2: never stored): Done over (total − StageCancelled),
	// optionally criteria-weighted. Rendered by board_read only. A zero
	// denominator renders no-progress (IsNull true), never 0/0.
	ProgressDone    int  `json:"progress_done"`
	ProgressTotal   int  `json:"progress_total"`
	ProgressDerived bool `json:"progress_derived"`
}

type EpicInput struct {
	Title    string
	Outcome  string
	Priority string
	Tags     []string
}

type Event struct {
	ID        string          `json:"id"`
	ProjectID string          `json:"project_id"`
	ItemKind  string          `json:"item_kind,omitempty"`
	ItemID    string          `json:"item_id,omitempty"`
	Action    string          `json:"action"`
	Actor     json.RawMessage `json:"actor"`
	Payload   json.RawMessage `json:"payload,omitempty"`
	CreatedAt time.Time       `json:"created_at"`
}

type Failpoint func(where string) error

type GuardError struct {
	Code   string
	Detail string
}

type HeartbeatResult struct {
	Extended       bool      `json:"extended"`
	LeaseExpiresAt time.Time `json:"lease_expires_at"`
	LastProgressAt time.Time `json:"last_progress_at"`
}

type NotFoundError struct {
	Item        string
	Identifier  string
	Suggestions []string
}

type Option func(*Service)

type PRDriftSource interface {
	GetPullRequest(ctx context.Context, prNumber int) (PRState, error)
}

type PRState struct {
	Merged bool
	Closed bool
	URL    string
}

type PendingInputSource interface {
	PendingInput(ctx context.Context, assigneeSession string) (PendingInputState, error)
}

type PendingInputState struct {
	HasPendingInput bool
}

type Project struct {
	ID                string     `json:"id"`
	ShortID           string     `json:"short_id"`
	UserID            string     `json:"user_id"`
	Name              string     `json:"name"`
	TargetWorkspaceID string     `json:"target_workspace_id,omitempty"`
	WorkerSlots       int        `json:"worker_slots"`
	SlotCooldownUntil *time.Time `json:"slot_cooldown_until,omitempty"`
	Tags              []string   `json:"tags"`
	Status            string     `json:"status"`
	CreatedAt         time.Time  `json:"created_at"`
	UpdatedAt         time.Time  `json:"updated_at"`
}

type ProjectInput struct {
	Name              string
	TargetWorkspaceID string
	WorkerSlots       int
	Tags              []string
}

type Queryer interface {
	Exec(ctx context.Context, sql string, args ...any) (pgconn.CommandTag, error)
	Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
	QueryRow(ctx context.Context, sql string, args ...any) pgx.Row
}

type Reconciler struct {
	// contains filtered or unexported fields
}

type Service struct {
	// contains filtered or unexported fields
}

type Store struct {
	// contains filtered or unexported fields
}

type SweepResult struct {
	Dispatched      int `json:"dispatched"`       // §4.4 sweep-backstop drive
	Reclaims        int `json:"reclaims"`         // RC1
	DriftDone       int `json:"drift_done"`       // RC2 merged, criteria met
	DriftReview     int `json:"drift_review"`     // RC2 merged, criteria unmet
	DriftReentry    int `json:"drift_reentry"`    // RC2 closed-unmerged → in_progress
	DepRepairs      int `json:"dep_repairs"`      // RC3 is_blocked recomputes
	AbandonedStaged int `json:"abandoned_staged"` // RC3 canceled-dependency flips
	PendingStaged   int `json:"pending_staged"`   // pending-input auto-stage (worker origin)
	Resumes         int `json:"resumes"`          // pending-input resolutions (lease re-armed)
	EpicCompletions int `json:"epic_completions"` // RC4 net
}

type Task struct {
	ID                 string                `json:"id"`
	ProjectID          string                `json:"project_id"`
	EpicID             string                `json:"epic_id"`
	ShortID            string                `json:"short_id"`
	Title              string                `json:"title"`
	Description        string                `json:"description"`
	Stage              string                `json:"stage"`
	PendingOrigin      *string               `json:"pending_origin,omitempty"`
	Priority           string                `json:"priority"`
	ProjectName        string                `json:"project_name"`
	EpicName           string                `json:"epic_name"`
	Tags               []string              `json:"tags"`
	AcceptanceCriteria []AcceptanceCriterion `json:"acceptance_criteria"`
	IsBlocked          bool                  `json:"is_blocked"`
	BlockedBy          []string              `json:"blocked_by,omitempty"` // derived: non-done dependency short IDs
	AssigneeSession    string                `json:"assignee_session,omitempty"`
	ClaimToken         string                `json:"claim_token,omitempty"`
	LeaseExpiresAt     *time.Time            `json:"lease_expires_at,omitempty"`
	LastProgressAt     *time.Time            `json:"last_progress_at,omitempty"`
	Attempts           int                   `json:"attempts"`
	ClaimIncremented   bool                  `json:"claim_incremented_attempts"`
	CooldownUntil      *time.Time            `json:"cooldown_until,omitempty"`
	StageEnteredAt     time.Time             `json:"stage_entered_at"`
	CreatedAt          time.Time             `json:"created_at"`
	UpdatedAt          time.Time             `json:"updated_at"`
}

type TaskInput struct {
	Title              string
	Description        string
	Priority           string
	Tags               []string
	AcceptanceCriteria []AcceptanceCriterion
	// SetCriteriaMet checks off the criterion at this 0-based index.
	SetCriteriaMet *int
}

type Transition struct {
	ID          int64           `json:"id"`
	TaskID      string          `json:"task_id"`
	FromStage   string          `json:"from_stage"`
	ToStage     string          `json:"to_stage"`
	EvidenceURL string          `json:"evidence_url,omitempty"`
	Actor       json.RawMessage `json:"actor"`
	At          time.Time       `json:"at"`
}

type WorkerAborter func(ctx context.Context, taskID, assigneeSession string) error

type WorkerSpawner func(ctx context.Context, claim *Claim) (sessionID string, err error)