threads

type Thread struct {
	ID                 string          `json:"id" example:"thr_01HK7R8Z"`
	Kind               string          `json:"kind" example:"correction"`
	TargetType         string          `json:"target_type" example:"asset"`
	AssetID            string          `json:"asset_id,omitempty"`
	CollectionID       string          `json:"collection_id,omitempty"`
	PromptID           string          `json:"prompt_id,omitempty"`
	KnowledgePageID    string          `json:"knowledge_page_id,omitempty"`
	Anchor             json.RawMessage `json:"anchor,omitempty" swaggertype:"object"`
	TargetVersion      int             `json:"target_version,omitempty"`
	Title              string          `json:"title,omitempty"`
	AuthorID           string          `json:"author_id"`
	AuthorEmail        string          `json:"author_email" example:"sme@example.com"`
	Status             string          `json:"status" example:"open"`
	RequiresResolution bool            `json:"requires_resolution"`
	ValidationState    string          `json:"validation_state" example:"none"`
	InsightID          string          `json:"insight_id,omitempty"`
	CreatedAt          time.Time       `json:"created_at"`
	UpdatedAt          time.Time       `json:"updated_at"`
	DeletedAt          *time.Time      `json:"deleted_at,omitempty"`
}

type ThreadEvent struct {
	ID            string          `json:"id" example:"evt_01HK7R8Z"`
	ThreadID      string          `json:"thread_id"`
	EventType     string          `json:"event_type" example:"comment"`
	AuthorID      string          `json:"author_id"`
	AuthorEmail   string          `json:"author_email"`
	Body          string          `json:"body,omitempty"`
	Rating        *int            `json:"rating,omitempty"`
	ParentEventID string          `json:"parent_event_id,omitempty"`
	Metadata      json.RawMessage `json:"metadata,omitempty" swaggertype:"object"`
	CreatedAt     time.Time       `json:"created_at"`
}

type ThreadFilter struct {
	TargetType         string
	AssetID            string
	CollectionID       string
	PromptID           string
	KnowledgePageID    string
	Kind               string
	Status             string
	RequiresResolution *bool
	ValidationState    string
	// AuthorID / AuthorEmail restrict to threads opened by this user (used by the
	// SME "awaiting my validation" worklist). When both are set the match is an
	// OR (id or case-insensitive email), matching how respond-permission resolves
	// the author, so a thread answerable by the caller cannot be missing from
	// their worklist.
	AuthorID    string
	AuthorEmail string
	// TargetAssetIDs / TargetCollectionIDs / TargetPromptIDs restrict to threads
	// on any of the given assets, collections, OR prompts. The practitioner
	// worklist sets assets+collections (artifacts the caller owns or can edit);
	// the feedback activity feed sets all three (every artifact the caller can
	// view). When any is set the match is an OR across the populated target
	// types.
	TargetAssetIDs      []string
	TargetCollectionIDs []string
	TargetPromptIDs     []string
	// IncludeStandalone adds standalone-channel threads to the target-id OR group
	// (used by the agent feedback feed, which spans the caller's artifacts AND the
	// shared general channel). On its own it matches all standalone threads.
	IncludeStandalone bool
	// Unresolved restricts to threads in a non-terminal status (anything other
	// than resolved or wont_fix), i.e. feedback that still needs attention.
	Unresolved bool
	// ExcludeAuthorID / ExcludeAuthorEmail drop threads opened by this user, so a
	// caller's own threads are not surfaced as feedback awaiting their action.
	ExcludeAuthorID    string
	ExcludeAuthorEmail string
	Limit              int
	Offset             int
}

type ThreadStore interface {
	// CreateThread inserts a thread and its first event atomically and returns
	// the stored thread with server-assigned timestamps.
	CreateThread(ctx context.Context, t Thread, first ThreadEvent) (*Thread, error)
	// ListThreads returns matching threads (with timeline aggregates) plus the
	// total count for pagination.
	ListThreads(ctx context.Context, filter ThreadFilter) ([]ThreadWithMeta, int, error)
	// GetThread returns a single non-deleted thread by id.
	GetThread(ctx context.Context, id string) (*Thread, error)
	// ListEvents returns a thread's events oldest-first.
	ListEvents(ctx context.Context, threadID string) ([]ThreadEvent, error)
	// AppendEvent inserts an event and bumps the thread's updated_at.
	AppendEvent(ctx context.Context, e ThreadEvent) (*ThreadEvent, error)
	// UpdateThread applies the update and, when the status changes, records a
	// status_change/resolution event in the same transaction.
	UpdateThread(ctx context.Context, id string, u ThreadUpdate, actorID, actorEmail string) error
	// SoftDeleteThread marks a thread deleted.
	SoftDeleteThread(ctx context.Context, id string) error
	// LinkInsight links one or more threads to a captured insight: it sets
	// insight_id, appends an insight_linked event, and transitions the thread to
	// resolved, atomically per thread. Threads that are missing or already
	// deleted are skipped. It returns the IDs of the threads that were actually
	// linked, so the caller can detect (and report) thread_ids that matched
	// nothing. This is the bridge from feedback into the knowledge loop
	// (Phase 2 / #602).
	LinkInsight(ctx context.Context, threadIDs []string, insightID, actorID, actorEmail string) ([]string, error)
	// RequestValidation moves a thread to validation_state=pending and records a
	// validation_request event, atomically.
	RequestValidation(ctx context.Context, id, actorID, actorEmail string) error
	// RespondValidation records an SME's validation outcome (validated/disputed),
	// appends a validation_result event, and re-opens the thread when disputed.
	RespondValidation(ctx context.Context, id string, resp ValidationResponse, actorID, actorEmail string) error
	// CountOpenByTargets returns, per target id, the number of open (non-deleted)
	// threads. targetType must be asset/collection/prompt. Callers are
	// responsible for restricting ids to those the requester may see.
	CountOpenByTargets(ctx context.Context, targetType string, ids []string) (map[string]int, error)
	// CountSignoffs returns the number of distinct users who left an approval
	// (signoff) event on any thread targeting the given asset/collection.
	CountSignoffs(ctx context.Context, targetType, targetID string) (int, error)
}

type ThreadUpdate struct {
	Status             *string
	RequiresResolution *bool
	ValidationState    *string
}

type ThreadWithMeta struct {
	Thread
	EventCount    int       `json:"event_count"`
	LastEventAt   time.Time `json:"last_event_at"`
	LastEventType string    `json:"last_event_type,omitempty"`
}

type ValidationResponse struct {
	Result string // ValidationStateValidated or ValidationStateDisputed
	Reason string // optional; recorded on the validation_result event
}