knowledge

type ApplyChange struct {
	ChangeType       string `json:"change_type"`
	Target           string `json:"target"`
	Detail           string `json:"detail"`
	QuerySQL         string `json:"query_sql,omitempty"`
	QueryDescription string `json:"query_description,omitempty"`
}

type ApplyConfig struct {
	Enabled             bool `yaml:"enabled"`
	RequireConfirmation bool `yaml:"require_confirmation"`
}

type BackfillStats struct {
	PagesScanned int `json:"pages_scanned"`
	InlineRefs   int `json:"inline_refs"`
	PromotedRefs int `json:"promoted_refs"`
}

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

type CatalogReach func(ctx context.Context, reference string) bool

type Changeset struct {
	ID               string         `json:"id" example:"cs_x1y2z3a4b5c6d7e8"`
	CreatedAt        time.Time      `json:"created_at" example:"2026-01-15T16:00:00Z"`
	TargetURN        string         `json:"target_urn" example:"mcp:dataset:(trino,warehouse,hive.sales.orders)"`
	ChangeType       string         `json:"change_type" example:"update_description"`
	PreviousValue    map[string]any `json:"previous_value"`
	NewValue         map[string]any `json:"new_value"`
	SourceInsightIDs []string       `json:"source_insight_ids"`
	ApprovedBy       string         `json:"approved_by" example:"admin@example.com"`
	AppliedBy        string         `json:"applied_by" example:"admin@example.com"`
	RolledBack       bool           `json:"rolled_back" example:"false"`
	RolledBackBy     string         `json:"rolled_back_by,omitempty"`
	RolledBackAt     *time.Time     `json:"rolled_back_at,omitempty"`
}

type ChangesetFilter struct {
	EntityURN string
	AppliedBy string
	// SourceInsightID filters to changesets whose source_insight_ids array
	// contains this insight id (the thread -> insight -> changeset bridge).
	SourceInsightID string
	Since           *time.Time
	Until           *time.Time
	RolledBack      *bool
	Limit           int
	Offset          int
}

type ChangesetStore interface {
	InsertChangeset(ctx context.Context, cs Changeset) error
	GetChangeset(ctx context.Context, id string) (*Changeset, error)
	ListChangesets(ctx context.Context, filter ChangesetFilter) ([]Changeset, int, error)
	RollbackChangeset(ctx context.Context, id, rolledBackBy string) error
}

type EntityInsightSummary struct {
	EntityURN  string   `json:"entity_urn"`
	Count      int      `json:"count"`
	Categories []string `json:"categories"`
	LatestAt   string   `json:"latest_at"`
}

type EntityMetadata struct {
	Description   string   `json:"description"`
	Tags          []string `json:"tags"`
	GlossaryTerms []string `json:"glossary_terms"`
	Owners        []string `json:"owners"`
}

type Insight struct {
	ID               string            `json:"id" example:"a1b2c3d4e5f67890a1b2c3d4e5f67890"`
	CreatedAt        time.Time         `json:"created_at" example:"2026-01-15T14:30:00Z"`
	SessionID        string            `json:"session_id" example:"sess_abc123"`
	CapturedBy       string            `json:"captured_by" example:"analyst@example.com"`
	Persona          string            `json:"persona" example:"analyst"`
	Source           string            `json:"source" example:"user"`
	Category         string            `json:"category" example:"correction"`
	InsightText      string            `json:"insight_text" example:"The amount column represents gross margin before returns, not revenue."`
	Confidence       string            `json:"confidence" example:"high"`
	EntityURNs       []string          `json:"entity_urns"`
	RelatedColumns   []RelatedColumn   `json:"related_columns"`
	SuggestedActions []SuggestedAction `json:"suggested_actions"`
	Status           string            `json:"status" example:"pending"`
	// SinkClass is the #633 organizing axis carried onto the backing memory
	// record so the unified write path and apply_knowledge sink router can
	// route by it. Empty for insights captured before #633.
	SinkClass string `json:"sink_class,omitempty" example:"schema_entity"`

	// Lifecycle fields (populated by migrations 000007 and 000008)
	ReviewedBy  string     `json:"reviewed_by,omitempty" example:"admin@example.com"`
	ReviewedAt  *time.Time `json:"reviewed_at,omitempty"`
	ReviewNotes string     `json:"review_notes,omitempty" example:"Verified with data engineering team"`
	// AppliedBy, AppliedAt and ChangesetRef record the last application. They are
	// retained when a rollback returns the insight to the review queue (#1257), so
	// the next reviewer sees the destination and changeset that were already tried
	// rather than deciding blind; a pending insight carrying them is one whose
	// application was reverted.
	AppliedBy    string     `json:"applied_by,omitempty"`
	AppliedAt    *time.Time `json:"applied_at,omitempty"`
	ChangesetRef string     `json:"changeset_ref,omitempty"`
}

type InsightFilter struct {
	Status     string
	Category   string
	EntityURN  string
	CapturedBy string
	Confidence string
	Source     string
	Since      *time.Time
	Until      *time.Time
	Limit      int
	Offset     int
	// OrderCreatedAsc lists insights oldest-first (created_at ASC) instead of the
	// default newest-first (created_at DESC). The review queue uses it to work the
	// oldest, stalest review debt first (#764).
	OrderCreatedAsc bool
	// Shared lists the applied insights of every capturer rather than one
	// owner's. Like InsightSearchQuery.Shared it overrides CapturedBy and Status
	// together, so listing across owners cannot be reached without pinning the
	// applied status (#980 B2).
	Shared bool
}

type InsightSearchQuery struct {
	QueryText  string
	Embedding  []float32
	CapturedBy string
	Status     string
	Limit      int
	// Shared requests the organization-wide arm instead of the owner arm: the
	// applied insights of every capturer, not the caller's own. It is a single
	// flag rather than "leave CapturedBy empty" so that reaching across owners
	// is impossible without also pinning the status — the adapter overrides
	// both CapturedBy and Status together (see sharedInsightScope), so a caller
	// that forgets to set an owner gets applied insights, never everyone's
	// private pending captures (#980 B2).
	Shared bool
}

type InsightSearcher interface {
	Search(ctx context.Context, q InsightSearchQuery) ([]ScoredInsight, error)
}

type InsightStats struct {
	TotalPending int                    `json:"total_pending"`
	ByEntity     []EntityInsightSummary `json:"by_entity"`
	ByCategory   map[string]int         `json:"by_category"`
	ByConfidence map[string]int         `json:"by_confidence"`
	ByStatus     map[string]int         `json:"by_status"`
	// OldestPendingAt is the created_at of the oldest pending insight, or nil
	// when the pending queue is empty. It surfaces review-queue staleness so
	// pending insights do not silently age (#764).
	OldestPendingAt *time.Time `json:"oldest_pending_at,omitempty"`
	// PendingOver30d counts pending insights older than
	// PendingStalenessThresholdDays, the accumulating review debt (#764).
	PendingOver30d int `json:"pending_over_30d"`
}

type InsightStore interface {
	Insert(ctx context.Context, insight Insight) error
	Get(ctx context.Context, id string) (*Insight, error)
	List(ctx context.Context, filter InsightFilter) ([]Insight, int, error)
	UpdateStatus(ctx context.Context, id, status, reviewedBy, reviewNotes string) error
	Update(ctx context.Context, id string, updates InsightUpdate) error
	Stats(ctx context.Context, filter InsightFilter) (*InsightStats, error)
	MarkApplied(ctx context.Context, id, appliedBy, changesetRef string) error
	// ReturnToReview sends an applied insight back to pending after its changeset
	// was rolled back (#1257), so the review queue surfaces it for a decision
	// again. The prior application is retained (applied_by, applied_at,
	// changeset_ref) and the rollback is recorded in the review fields, so the
	// next reviewer sees what was already tried. It returns whether the insight
	// was in the applied state and was transitioned: an insight in any other
	// state is left alone (returned == false, no error), so re-running a rollback
	// neither errors nor resurrects an insight somebody has since decided.
	ReturnToReview(ctx context.Context, id, rolledBackBy, changesetID string) (returned bool, err error)
	Supersede(ctx context.Context, entityURN string, excludeID string) (int, error)
}

type InsightUpdate struct {
	InsightText string `json:"insight_text,omitempty"`
	Category    string `json:"category,omitempty"`
	Confidence  string `json:"confidence,omitempty"`
}

type InstructionsEditedError struct {
	Section string
}

type InstructionsStore interface {
	// AgentInstructions returns the deployment's customized instruction text, or
	// "" when the deployment has never set one (which the sink writes into: a
	// first promotion creates the value, the way a first page promotion creates
	// the page).
	AgentInstructions(ctx context.Context) (string, error)
	// SetAgentInstructions replaces the customized instruction text, recording
	// author as the writer.
	SetAgentInstructions(ctx context.Context, value, author string) error
}

type PageEditedError struct {
	Slug             string
	CurrentVersion   int
	ChangesetVersion int
}

type PageReverter interface {
	GetBySlug(ctx context.Context, slug string) (*knowledgepage.Page, error)
	Update(ctx context.Context, id string, updates knowledgepage.Update) error
	SoftDelete(ctx context.Context, id string) error
	// Entity references (#664): restore the page's promoted references on rollback,
	// scoped to source=promoted so manual and inline references are not clobbered.
	ReplaceEntityRefsBySource(ctx context.Context, pageID, source string, refs []knowledgepage.EntityRef) error
}

type PendingReview struct {
	TotalPending    int        `json:"total_pending"`
	OldestPendingAt *time.Time `json:"oldest_pending_at,omitempty"`
	PendingOver30d  int        `json:"pending_over_30d"`
}

type PromptCreator interface {
	Create(ctx context.Context, p *prompt.Prompt) error
	RegisterRuntimePrompt(p *prompt.Prompt)
}

type ProposedChange struct {
	ChangeType       string   `json:"change_type"`
	Target           string   `json:"target"`
	CurrentValue     string   `json:"current_value"`
	SuggestedValue   string   `json:"suggested_value"`
	SourceInsightIDs []string `json:"source_insight_ids"`
}

type RelatedColumn struct {
	URN       string `json:"urn" example:"mcp:dataset:(trino,warehouse,hive.sales.orders)"`
	Column    string `json:"column" example:"amount"`
	Relevance string `json:"relevance" example:"direct"`
}

type RequiredFieldError string

type RollbackConflictError struct {
	Conflict *catalog.ConflictError
}

type RollbackDeps struct {
	// Catalog is the platform catalog a catalog changeset is rolled back in.
	Catalog    catalog.Store
	Changesets ChangesetStore
	Insights   InsightStore
	// Pages reverts knowledge-page promotions (target "kp:<slug>"). Optional; a
	// nil Pages makes a page-changeset rollback return a clear "not configured"
	// error rather than mis-routing through the catalog path.
	// PageReverter and PageEditedError live in page_sink.go with the rest of the
	// page-sink machinery.
	Pages PageReverter
	// Instructions reverts promotions into the deployment's customized agent
	// instructions (target "ai:<section>"). Optional; a nil Instructions makes an
	// instructions-changeset rollback return a clear "not configured" error rather
	// than mis-routing through the catalog path. InstructionsStore and
	// InstructionsEditedError live in instructions_sink.go with the rest of that
	// sink's machinery.
	Instructions InstructionsStore
}

type RollbackResult struct {
	ChangesetID     string   `json:"changeset_id"`
	TargetURN       string   `json:"target_urn"`
	RevertedChanges []string `json:"reverted_changes"`
	SkippedChanges  []string `json:"skipped_changes,omitempty"`
	// InsightsReturnedToReview lists the source insights the rollback sent back to
	// the review queue as pending (#1257). Only insights that actually moved are
	// listed: one already returned by an earlier rollback, or since decided some
	// other way, is left as it is.
	InsightsReturnedToReview []string `json:"insights_returned_to_review"`
	RolledBackBy             string   `json:"rolled_back_by,omitempty"`
}

type ScoredInsight struct {
	Insight Insight
	Score   float64
}

type SearchableInsightStore interface {
	InsightStore
	InsightSearcher
}

type SuggestedAction struct {
	ActionType       string `json:"action_type" example:"update_description"`
	Target           string `json:"target" example:"amount"`
	Detail           string `json:"detail" example:"Gross margin before returns"`
	QuerySQL         string `json:"query_sql,omitempty"`
	QueryDescription string `json:"query_description,omitempty"`
}

type ToolInventory func() []string

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

type UnrevertibleError struct {
	ChangeTypes []string
}