threads

package
v1.155.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package threads holds the portal feedback-thread data layer: the Thread types and constants, the ThreadStore interface, its PostgreSQL implementation, and the filter/query helpers. It was split out of the portal package (issue #594, package-size gate) so the bulk of the thread substrate lives in a cohesive, independently-reasoned package; the HTTP handlers that drive it remain in portal, which re-exports these symbols under their original names.

Index

Constants

View Source
const (
	ThreadKindComment    = "comment"
	ThreadKindQuestion   = "question"
	ThreadKindCorrection = "correction"
	ThreadKindRating     = "rating"
	ThreadKindApproval   = "approval"
	ThreadKindRejection  = "rejection"
	ThreadKindSuggestion = "suggestion"
)

Thread kinds. A kind is the human-facing classification of a feedback thread; it is stored on the thread and also determines the event_type of the thread's first event (see DeriveFirstEventType).

View Source
const (
	ThreadStatusOpen         = "open"
	ThreadStatusAnswered     = "answered"
	ThreadStatusResolved     = "resolved"
	ThreadStatusWontFix      = "wont_fix"
	ThreadStatusAcknowledged = "acknowledged"
)

Thread statuses.

View Source
const (
	EventTypeComment           = "comment"
	EventTypeStatusChange      = "status_change"
	EventTypeResolution        = "resolution"
	EventTypeRating            = "rating"
	EventTypeApproval          = "approval"
	EventTypeRejection         = "rejection"
	EventTypeValidationRequest = "validation_request"
	EventTypeValidationResult  = "validation_result"
	EventTypeInsightLinked     = "insight_linked"
	EventTypeChangesetLinked   = "changeset_linked"
)

Thread event types. comment is one event type among many; status changes, resolutions, ratings, approvals, and the Phase 2 knowledge-link events all share the same timeline.

View Source
const (
	ValidationStateNone      = "none"
	ValidationStatePending   = "pending"
	ValidationStateValidated = "validated"
	ValidationStateDisputed  = "disputed"
)

Thread validation states (validation/signoff lifecycle lands in Phase 3; the column and these values exist so the substrate is forward-compatible).

View Source
const (
	// VisibilityInternal is a thread the organization's own people see.
	VisibilityInternal = "internal"
	// VisibilityShared is a thread everyone who can open its target sees,
	// external people included.
	VisibilityShared = "shared"
	// EventTypeVisibilityChange records a thread made internal or shared.
	EventTypeVisibilityChange = "visibility_changed"
)

Thread visibilities (#2227).

View Source
const (
	DefaultThreadLimit = defaultThreadLimit
	MaxThreadLimit     = maxThreadLimit
)

DefaultThreadLimit and MaxThreadLimit are exported for the portal list handlers, which parse and clamp the page size before calling the store.

View Source
const StatusUndoWindow = 10 * time.Minute

StatusUndoWindow is how long after a status change its author may undo it.

Variables

View Source
var (
	// ErrEventNotFound is a message that is not in the thread.
	ErrEventNotFound = errors.New("thread event not found")
	// ErrEventNotEditable is an event that records a decision or a link,
	// which is never edited or deleted.
	ErrEventNotEditable = errors.New("only comment and reply text can be edited or deleted")
	// ErrEventDeleted is a message already deleted.
	ErrEventDeleted = errors.New("the message was deleted")
)

Errors an edit or delete refuses with.

View Source
var (
	// ErrUndoNotStatus is an event that is not a status change.
	ErrUndoNotStatus = errors.New("only a status change can be undone")
	// ErrUndoNotAuthor is a caller who did not make the change.
	ErrUndoNotAuthor = errors.New("only the person who changed the status can undo it")
	// ErrUndoExpired is a change older than StatusUndoWindow.
	ErrUndoExpired = errors.New("a status change can be undone for 10 minutes; pick the earlier status instead")
	// ErrUndoSuperseded is a change someone else has added to the thread
	// since, or one a later change replaced.
	ErrUndoSuperseded = errors.New("the thread changed since; pick the earlier status instead")
)

Errors an undo refuses with.

Functions

func DeriveFirstEventType

func DeriveFirstEventType(kind string) string

DeriveFirstEventType maps a thread kind to the event_type its initial event carries: rating/approval/rejection keep their own semantic; everything else (comment/question/correction/suggestion) is a plain comment event. Exported for the portal createThread handler, which owns thread creation.

func FirstLineSnippet added in v1.153.2

func FirstLineSnippet(body string) string

FirstLineSnippet returns the first non-blank line of a message, trimmed and cut to firstMessageRunes with an ellipsis (#2513).

func NewThreadEventID

func NewThreadEventID() string

NewThreadEventID returns a unique id for a thread event. Exported so callers outside the package (the portal toolkit) can mint event ids for AppendEvent.

func NewThreadID

func NewThreadID(prefix string) string

NewThreadID returns a prefixed unique id (e.g. "thr_<uuid>", "evt_<uuid>").

func ValidThreadKind

func ValidThreadKind(kind string) bool

ValidThreadKind reports whether kind is one of the seven authoring kinds.

func ValidThreadStatus

func ValidThreadStatus(status string) bool

ValidThreadStatus reports whether status is a recognized thread status.

func ValidThreadValidationState

func ValidThreadValidationState(s string) bool

ValidThreadValidationState reports whether s is a recognized validation state.

func ValidVisibility added in v1.149.0

func ValidVisibility(v string) bool

ValidVisibility reports whether v is a thread visibility.

Types

type EventEdit added in v1.153.2

type EventEdit struct {
	ThreadID string
	EventID  string
	Body     string
	// Metadata is the event's metadata after the edit, carrying the mentions
	// the new text delivers.
	Metadata json.RawMessage
	// EditorEmail is who made the change, kept beside the previous text.
	EditorEmail string
}

EventEdit is one change to a message's text.

type EventEditor added in v1.153.2

type EventEditor interface {
	// GetEvent returns one event of the thread, its text withheld when it
	// was deleted.
	GetEvent(ctx context.Context, threadID, eventID string) (*ThreadEvent, error)
	// EditEvent replaces a comment's text, keeping the previous text, and
	// returns the event as it now reads.
	EditEvent(ctx context.Context, e EventEdit) (*ThreadEvent, error)
	// DeleteEvent marks a comment deleted. When it is the thread's opening
	// message and nothing else was said, the thread is deleted with it and
	// threadDeleted is true.
	DeleteEvent(ctx context.Context, threadID, eventID, actorEmail string) (threadDeleted bool, err error)
	// Participants returns the lower-cased addresses of everyone who wrote a
	// message in the thread that is not deleted, or is mentioned in one.
	Participants(ctx context.Context, threadID string) ([]string, error)
}

EventEditor edits and deletes one message of a thread and lists the people a thread involves. The PostgreSQL thread store implements it; it is apart from ThreadStore so the stores that never change a message need not.

type MessageNotice added in v1.153.2

type MessageNotice struct {
	Thread     *Thread
	EventID    string
	ActorEmail string
	Body       string
	// Mentioned are the people the message mentions who can open the target.
	Mentioned []string
	// MentionsOnly notifies the mentioned people and nobody else, for an
	// edit that newly names someone (#2514).
	MentionsOnly bool
}

MessageNotice is what one message tells the people a thread involves: the message, who wrote it, and the people its text mentions (#2512).

type StatusUndo added in v1.154.1

type StatusUndo struct {
	ThreadID   string
	EventID    string
	ActorID    string
	ActorEmail string
	// Now is when the undo is asked, which the window is measured to.
	Now time.Time
}

StatusUndo names the change to undo and who asks.

type StatusUndoer added in v1.154.1

type StatusUndoer interface {
	// UndoStatusChange restores the status the event replaced and removes
	// the event, returning the restored status.
	UndoStatusChange(ctx context.Context, u StatusUndo) (string, error)
}

StatusUndoer takes back a status change. The PostgreSQL thread store implements it; it is apart from ThreadStore so the stores that never undo need not.

type Thread

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"`
	// Visibility is internal or shared (#2227): people of an external persona
	// never see an internal thread, and a thread one of them opens is shared.
	Visibility string `json:"visibility" example:"internal"`
}

Thread is a tracked feedback work item with a target, a lifecycle, and a typed event timeline. Exactly one of AssetID/CollectionID/PromptID is set for asset/collection/prompt target types; all are empty for standalone.

func (*Thread) TargetID added in v1.114.0

func (t *Thread) TargetID() string

TargetID returns the id of whichever object the thread targets, empty for the standalone channel. Exactly one target field is set on a row, so the order of the cases is a formality rather than a precedence rule.

type ThreadEvent

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"`
	// EditedAt is when the author last changed the text (#2514); the text
	// before each edit is kept in portal_thread_event_revisions.
	EditedAt *time.Time `json:"edited_at,omitempty"`
	// DeletedAt marks a deleted message (#2514). Every read returns it with
	// no body and no metadata, so its place in the timeline stays and its
	// text reaches nobody.
	DeletedAt *time.Time `json:"deleted_at,omitempty"`
}

ThreadEvent is one entry in a thread's timeline.

type ThreadFilter

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
	// ActivityAfter restricts to threads whose timeline gained an event after
	// this instant, i.e. threads with activity the caller has not been shown
	// yet. Thread creation writes the thread's first event in the same
	// transaction, so a thread opened after the instant qualifies on its own
	// first event and needs no separate created-after clause.
	//
	// ExcludeAuthorID / ExcludeAuthorEmail apply to the event as well as the
	// thread: an event the excluded user wrote does not count as activity, so a
	// caller's own reply on their own asset's thread never re-raises it.
	ActivityAfter *time.Time
	// MentionedEmail restricts to threads holding an event that @-mentions this
	// address (#627), which is the "mentions of me" inbox. It matches the
	// mentions recorded on the event by the write path, not the token text, so
	// a name written for someone outside the target's audience -- stored as
	// plain text, notifying nobody -- never lands in their inbox either.
	MentionedEmail string
	// SharedOnly restricts to shared threads, which is all a person of an
	// external persona sees (#2227).
	SharedOnly bool
	Limit      int
	Offset     int
}

ThreadFilter selects threads for listing.

func (*ThreadFilter) EffectiveLimit

func (f *ThreadFilter) EffectiveLimit() int

EffectiveLimit returns the clamped page size, applying the default when unset.

type ThreadStore

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, sharedOnly bool) (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, sharedOnly bool) (int, error)
}

ThreadStore persists and queries feedback threads and their event timelines.

func NewPostgresThreadStore

func NewPostgresThreadStore(db *sql.DB) ThreadStore

NewPostgresThreadStore creates a PostgreSQL-backed thread store.

type ThreadUpdate

type ThreadUpdate struct {
	Status             *string
	RequiresResolution *bool
	ValidationState    *string
	// Visibility makes the thread internal or shared (#2227); a change is
	// recorded as a timeline event.
	Visibility *string
}

ThreadUpdate carries optional thread mutations. A nil field is left unchanged.

type ThreadWithMeta

type ThreadWithMeta struct {
	Thread
	EventCount    int       `json:"event_count"`
	LastEventAt   time.Time `json:"last_event_at"`
	LastEventType string    `json:"last_event_type,omitempty"`
	// FirstMessage is the first line of the thread's first message, cut to a
	// snippet (#2513). A thread is listed by it, its author and its target:
	// new threads carry no title.
	FirstMessage string `json:"first_message,omitempty"`
}

ThreadWithMeta is a thread list row enriched with timeline aggregates so the feedback panel can render activity without an N+1 fan-out over events.

type ValidationResponse

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

ValidationResponse is an SME's answer to a validation request (Phase 3 / #603).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL