hc

type Comment struct {
	ID        string    `json:"id"`
	ItemID    string    `json:"item_id"`
	Message   string    `json:"message"`
	CreatedAt time.Time `json:"created_at"`
}

type ContextBlock struct {
	Epic         Item              `json:"epic"`
	Counts       TaskCounts        `json:"counts"`
	MyTasks      []TaskWithComment `json:"my_tasks"`
	AllOpenTasks []Item            `json:"all_open_tasks"`
}

type CreateInput struct {
	Ref      string        `json:"ref,omitempty"` // optional local reference for blocker wiring
	Title    string        `json:"title"`
	Desc     string        `json:"desc,omitempty"`
	Type     ItemType      `json:"type"`
	Children []CreateInput `json:"children,omitempty"`
	Blockers []string      `json:"blockers,omitempty"` // refs of items that must complete before this one
}

type CreateItemInput struct {
	Title    string
	Desc     string
	Type     ItemType
	ParentID string
}

type Item struct {
	ID         string    `json:"id"`
	RepoKey    string    `json:"repo_key"`   // "owner/repo" or ""
	EpicID     string    `json:"epic_id"`    // "" for epics themselves
	ParentID   string    `json:"parent_id"`  // "" for root items
	SessionID  string    `json:"session_id"` // assigned agent session, may be ""
	Title      string    `json:"title"`
	Desc       string    `json:"desc"`
	Type       ItemType  `json:"type"`
	Status     Status    `json:"status"`
	Blocked    bool      `json:"-"`                     // computed at read time: true when the item has open/in_progress children or open/in_progress explicit blockers
	BlockerIDs []string  `json:"blocker_ids,omitempty"` // explicit blocker item IDs (open/in_progress only)
	Depth      int       `json:"depth"`                 // 0 for epics/roots
	CreatedAt  time.Time `json:"created_at"`
	UpdatedAt  time.Time `json:"updated_at"`
}

type ItemType string

type ItemUpdate struct {
	Status    *Status
	SessionID *string
	Title     *string
	Desc      *string
}

type ListFilter struct {
	RepoKey   string
	EpicID    string
	SessionID string
	Status    *Status
}

type NextFilter struct {
	EpicID    string
	SessionID string
	RepoKey   string
}

type PruneOpts struct {
	OlderThan time.Duration
	Statuses  []Status
	RepoKey   string
	DryRun    bool
}

type Status string

type Store interface {
	// CreateItems persists one or more items atomically.
	CreateItems(ctx context.Context, items []Item) error
	// GetItem returns an item by ID.
	GetItem(ctx context.Context, id string) (Item, error)
	// UpdateItem applies a partial update and returns the updated item.
	UpdateItem(ctx context.Context, id string, update ItemUpdate) (Item, error)
	// ListItems returns items matching the filter.
	ListItems(ctx context.Context, filter ListFilter) ([]Item, error)
	// NextItem returns the next actionable leaf item for the filter.
	// Actionable means status is open/in_progress and no open/in_progress children.
	NextItem(ctx context.Context, filter NextFilter) (Item, bool, error)
	// DeleteItem removes an item by ID.
	// This is an internal maintenance path used by prune operations.
	DeleteItem(ctx context.Context, id string) error
	// AddComment records a comment on an item.
	AddComment(ctx context.Context, c Comment) error
	// ListComments returns all comments for an item in chronological order.
	ListComments(ctx context.Context, itemID string) ([]Comment, error)
	// Prune removes old items and related comments according to options.
	Prune(ctx context.Context, opts PruneOpts) (int, error)
	// ListRepoKeys returns all distinct, non-empty repo keys in sorted order.
	ListRepoKeys(ctx context.Context) ([]string, error)
	// CreateBulkWithEdges creates items and wires their explicit blocker edges atomically.
	// edges is a slice of [blockerID, blockedID] pairs. Cycle validation must be done
	// by the caller before invoking this method; this method only enforces FK constraints.
	CreateBulkWithEdges(ctx context.Context, items []Item, edges [][2]string) error
	// AddBlocker records that blockerID blocks blockedID atomically, including cycle detection.
	// Returns ErrCyclicDependency if the edge would create a cycle.
	AddBlocker(ctx context.Context, blockerID, blockedID string) error
	// RemoveBlocker removes the blocker relationship.
	RemoveBlocker(ctx context.Context, blockerID, blockedID string) error
	// ListBlockers returns IDs of open/in_progress items that explicitly block the given item.
	ListBlockers(ctx context.Context, itemID string) ([]string, error)
	// ListBlockerEdges returns all blocker edges as [blockerID, blockedID] pairs.
	// Used by callers that need the full graph (e.g. for pre-validation before bulk create).
	ListBlockerEdges(ctx context.Context) ([][2]string, error)
	// BulkUpdateStatus sets the status of all non-terminal descendants of the given
	// epic to the specified status. Items already in a terminal status (done, cancelled)
	// are not modified.
	BulkUpdateStatus(ctx context.Context, epicID string, status Status) error
}

type TaskCounts struct {
	Open       int `json:"open"`
	InProgress int `json:"in_progress"`
	Done       int `json:"done"`
	Cancelled  int `json:"cancelled"`
}

type TaskWithComment struct {
	Item          Item    `json:"item"`
	LatestComment Comment `json:"latest_comment"`
}