memory

type DuplicateFinder interface {
	// SimilarActivePairs returns the createdBy owner's pairs of active,
	// embedded records with cosine similarity at or above minScore, highest
	// first, at most limit pairs. createdBy is required — memory content is
	// per-user, so an unscoped listing would expose other users' records.
	// Each record contributes its nearest neighbors only, so the listing is a
	// best-effort review queue, not an exhaustive join.
	SimilarActivePairs(ctx context.Context, createdBy string, minScore float64, limit int) ([]SimilarPair, error)
}

type Filter struct {
	CreatedBy string
	Persona   string
	Dimension string
	// SinkClass filters on the #633 organizing axis (personal_preference,
	// business_knowledge, schema_entity, operational_rule, episodic_event). It is
	// the lifecycle axis the portal Memory view browses by; unlike Dimension, it
	// distinguishes the three reviewable knowledge-dimension classes from one
	// another.
	SinkClass string
	Category  string
	Status    string
	Source    string
	EntityURN string
	Since     *time.Time
	Until     *time.Time
	Limit     int
	Offset    int
	// SortBy overrides the default ordering column (created_at). It must
	// be a key of ValidSortColumns; unknown columns fall back to the
	// default. ORDER BY cannot be parameterized, so the column is spliced
	// into SQL and only allowlisted values are accepted.
	SortBy string
	// SortDirection is one of SortAsc, SortDesc, SortAscNullsFirst, or
	// SortDescNullsLast. Unknown values fall back to SortDesc.
	SortDirection string
}

type HybridQuery struct {
	Embedding []float32
	QueryText string
	Limit     int
	CreatedBy string
	Dimension string
	// ExcludeDimension drops rows of one dimension from the results. It is
	// the complement of Dimension (which restricts to one): the unified
	// knowledge search excludes the knowledge dimension here because those
	// rows are served by the insights provider, and excluding them in SQL
	// (rather than after LIMIT) keeps the result count honest.
	ExcludeDimension string
	Persona          string
	Status           string
}

type LexicalQuery struct {
	QueryText string
	Limit     int
	CreatedBy string
	Dimension string
	// ExcludeDimension drops rows of one dimension; see HybridQuery.
	ExcludeDimension string
	Persona          string
	Status           string
}

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

type Record struct {
	ID        string    `json:"id" example:"mem_a1b2c3d4e5f6"`
	CreatedAt time.Time `json:"created_at" example:"2026-03-18T08:11:08Z"`
	UpdatedAt time.Time `json:"updated_at" example:"2026-03-18T08:11:08Z"`
	CreatedBy string    `json:"created_by" example:"sarah.chen@example.com"`
	Persona   string    `json:"persona" example:"admin"`
	Dimension string    `json:"dimension" example:"knowledge"`
	// SinkClass is the #633 organizing axis (personal_preference,
	// business_knowledge, schema_entity, operational_rule, episodic_event). It
	// drives routing in the unified write path. Empty on rows captured before
	// the axis existed; DeriveSinkClass reconstructs it from Dimension on read.
	SinkClass      string          `json:"sink_class,omitempty" example:"schema_entity"`
	Content        string          `json:"content" example:"The daily_sales table in the retail schema is partitioned by date."`
	Category       string          `json:"category" example:"business_context"`
	Confidence     string          `json:"confidence" example:"high"`
	Source         string          `json:"source" example:"user"`
	EntityURNs     []string        `json:"entity_urns"`
	RelatedColumns []RelatedColumn `json:"related_columns"`
	Embedding      []float32       `json:"embedding,omitempty"`
	// EmbeddingModel records the provider model that produced Embedding
	// (e.g. "nomic-embed-text"); EmbeddingTextHash is the SHA-256 of the
	// content fed to the embedder. They are the breadcrumbs the indexjobs
	// memory consumer uses to dedup re-embeds and detect model-swap gaps.
	// The synchronous write path stamps both when the embedder is healthy;
	// they are empty/nil on rows embedded before the column existed or
	// saved during an embedder outage (the reconciler later backfills).
	EmbeddingModel    string         `json:"embedding_model,omitempty"`
	EmbeddingTextHash []byte         `json:"embedding_text_hash,omitempty"`
	Metadata          map[string]any `json:"metadata"`
	Status            string         `json:"status" example:"active"`
	StaleReason       string         `json:"stale_reason,omitempty"`
	StaleAt           *time.Time     `json:"stale_at,omitempty"`
	LastVerified      *time.Time     `json:"last_verified,omitempty"`
}

type RecordUpdate struct {
	Content    string
	Category   string
	Confidence string
	Dimension  string
	// Status transitions the record's lifecycle column (active, archived,
	// superseded). Empty leaves it unchanged. Required so a status change made
	// via Update (e.g. an insight rejection that maps to archived) moves the
	// status column, not just metadata, so status-filtered reads honor it.
	Status    string
	Metadata  map[string]any
	Embedding []float32
	// EmbeddingModel and EmbeddingTextHash travel with Embedding: when an
	// update re-embeds changed content, the write path stamps the model
	// and content hash alongside the new vector so the row's breadcrumbs
	// stay consistent with the embedding the indexjobs consumer dedups on.
	EmbeddingModel    string
	EmbeddingTextHash []byte
}

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

type ScoredRecord struct {
	Record Record
	Score  float64
}

type SimilarPair struct {
	Older Record  `json:"older"`
	Newer Record  `json:"newer"`
	Score float64 `json:"score"`
}

type Snippet struct {
	ID         string    `json:"id"`
	Content    string    `json:"content"`
	Dimension  string    `json:"dimension"`
	Category   string    `json:"category"`
	Confidence string    `json:"confidence"`
	CreatedAt  time.Time `json:"created_at"`
}

type StalenessConfig struct {
	Interval  time.Duration
	BatchSize int
}

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

type Store interface {
	// Insert creates a new memory record.
	Insert(ctx context.Context, record Record) error

	// Get retrieves a single memory record by ID.
	Get(ctx context.Context, id string) (*Record, error)

	// Update modifies fields on an existing memory record.
	Update(ctx context.Context, id string, updates RecordUpdate) error

	// Delete soft-deletes a memory record by setting status to archived.
	Delete(ctx context.Context, id string) error

	// List returns memory records matching the filter with pagination.
	List(ctx context.Context, filter Filter) ([]Record, int, error)

	// VectorSearch performs cosine similarity search over embeddings.
	VectorSearch(ctx context.Context, query VectorQuery) ([]ScoredRecord, error)

	// HybridSearch fuses cosine similarity with a lexical full-text
	// signal for higher-quality recall on identifier-heavy content.
	HybridSearch(ctx context.Context, query HybridQuery) ([]ScoredRecord, error)

	// LexicalSearch ranks by Postgres full-text relevance only, the
	// graceful-degradation path when no embedding provider is available.
	LexicalSearch(ctx context.Context, query LexicalQuery) ([]ScoredRecord, error)

	// EntityLookup returns active memories linked to a DataHub URN. persona
	// narrows to one persona when set; createdBy narrows to one owner (the
	// per-user scope for search) when set. Either may be empty. When createdBy
	// is empty (the persona-scoped enrichment push path), pending insight
	// candidates are excluded so un-evaluated knowledge is not pushed into an
	// agent's context before it is grounded (#745).
	EntityLookup(ctx context.Context, urn, persona, createdBy string) ([]Record, error)

	// MarkStale flags memory records as stale with a reason.
	MarkStale(ctx context.Context, ids []string, reason string) error

	// MarkVerified updates the last_verified timestamp for records.
	MarkVerified(ctx context.Context, ids []string) error

	// Supersede marks an old record as superseded by a new one.
	Supersede(ctx context.Context, oldID, newID string) error
}

type VectorQuery struct {
	Embedding []float32
	Limit     int
	MinScore  float64
	CreatedBy string
	Dimension string
	Persona   string
	Status    string
	// ExcludeStatuses drops rows of the listed statuses, the complement of
	// Status (which restricts to one). It composes with the default archived
	// exclusion (applied when Status is empty). The recall-first capture check
	// uses it to skip superseded rows (a dead predecessor must not absorb a
	// new capture's supersede, #762) while still matching stale rows (a
	// restatement is exactly how a stale record gets corrected).
	ExcludeStatuses []string
}