native

type AdvanceLifecycleOptions struct {
	DwellHours           float64
	SurpriseGate         float64
	ImportanceGate       float64
	EditingWindowMinutes int
}

type AuditEvent struct {
	EventTime time.Time `json:"event_time"`
	Profile   string    `json:"profile"`
	Operation string    `json:"operation"`
	MemoryID  *string   `json:"memory_id,omitempty"`
	Details   any       `json:"details,omitempty"`
}

type AutoLink struct {
	ID         string  `json:"id"`
	Similarity float64 `json:"similarity"`
	Content    string  `json:"content,omitempty"`
}

type Breakdown struct {
	Name  string `json:"name"`
	Count int64  `json:"count"`
}

type CheckResult struct {
	Name     string        `json:"name"`
	OK       bool          `json:"ok"`
	Duration time.Duration `json:"duration_ns"`
	Detail   string        `json:"detail,omitempty"`
	Error    string        `json:"error,omitempty"`
}

type CleanupResult struct {
	Profile     string `json:"profile"`
	ExpiredSeen int    `json:"expired_seen"`
	Deleted     int    `json:"deleted"`
}

type ConfidenceResult struct {
	ID         string  `json:"id"`
	Profile    string  `json:"profile"`
	Confidence float64 `json:"confidence"`
}

type Config struct {
	Database  Database  `toml:"database"`
	Embedding Embedding `toml:"embedding"`
	Profile   string    `toml:"profile"`
}

type ConnectionSuggestion struct {
	ID             string    `json:"id"`
	Content        string    `json:"content"`
	SharedCount    int       `json:"shared_count"`
	SharedEntities []string  `json:"shared_entities"`
	CreatedAt      time.Time `json:"created_at"`
	Tags           []string  `json:"tags,omitempty"`
}

type CreateRelationshipOptions struct {
	SourceID     string
	TargetID     string
	Relationship string  // one of ValidRelationshipTypes
	Strength     float64 // default 1.0
	CreatedBy    string  // default "user"
	Metadata     map[string]any
}

type Database struct {
	// Backend is "postgres" (pgx direct) or "supabase" (PostgREST).
	// Auto-detected when empty: SUPABASE_URL => supabase, DATABASE_URL => postgres.
	Backend string `toml:"backend"`

	// URL is the Postgres connection string when Backend == "postgres".
	URL string `toml:"url"`

	// SupabaseURL is the project base URL (https://xxx.supabase.co) when
	// Backend == "supabase". REST endpoint derives as {URL}/rest/v1.
	SupabaseURL string `toml:"supabase_url"`
	SupabaseKey string `toml:"supabase_key"`
}

type DayCount struct {
	Day   time.Time `json:"day"`
	Count int64     `json:"count"`
}

type DecayResult struct {
	Profile  string `json:"profile"`
	Decayed  int    `json:"decayed"`
	DryRun   bool   `json:"dry_run"`
	Eligible int    `json:"eligible"`
}

type DeleteResult struct {
	ID      string `json:"id"`
	Profile string `json:"profile"`
}

type DimensionResult struct {
	Name   string  `json:"name"`
	Score  float64 `json:"score"`
	Zone   Zone    `json:"zone"`
	Detail string  `json:"detail"`
}

type Embedder interface {
	// Embed returns the embedding vector for text. Length must equal the
	// dimension the Embedder was configured with.
	Embed(ctx context.Context, text string) ([]float32, error)

	// Name returns a short identifier for error/log messages.
	Name() string

	// Dimension returns the output vector length. Callers that need to
	// assert schema compatibility (vector(512) etc.) can check here.
	Dimension() int
}

type Embedding struct {
	Provider  string `toml:"provider"`
	APIKey    string `toml:"api_key"`
	Model     string `toml:"model"`
	Dimension int    `toml:"dimension"`

	// BaseURL lets providers that can be self-hosted (Ollama today;
	// OpenAI via Azure / LocalAI proxies in v0.5+) point at a custom
	// endpoint instead of the provider default. Empty string means
	// "use provider default". Populated from OLLAMA_URL today; v0.5
	// embedders will add OPENAI_BASE_URL / MISTRAL_BASE_URL as they land.
	BaseURL string `toml:"base_url"`
}

type ExploreOptions struct {
	Depth       int      // default 1
	MinStrength float64  // default 0.5
	Limit       int      // default 5
	Tags        []string // filter seed results
	Source      string   // filter seed results
	Profile     string
}

type ExtendedHealthReport struct {
	Profile          string            `json:"profile"`
	OverallScore     float64           `json:"overall_score"`
	OverallZone      Zone              `json:"overall_zone"`
	Dimensions       []DimensionResult `json:"dimensions"`
	PortedDimensions int               `json:"ported_dimensions"`
	TotalDimensions  int               `json:"total_dimensions"`
	DeferredNotice   string            `json:"deferred_notice,omitempty"`
	DurationMs       float64           `json:"duration_ms"`
}

type FindRelatedOptions struct {
	Depth             int
	MinStrength       float64
	RelationshipTypes []string
	Limit             int
}

type GraphMemory struct {
	ID            string         `json:"id"`
	Content       string         `json:"content"`
	Metadata      map[string]any `json:"metadata,omitempty"`
	Source        string         `json:"source,omitempty"`
	Tags          []string       `json:"tags,omitempty"`
	Relevance     float64        `json:"relevance,omitempty"`
	Confidence    float64        `json:"confidence,omitempty"`
	Depth         int            `json:"depth"`
	Relationship  string         `json:"relationship,omitempty"`
	EdgeStrength  float64        `json:"edge_strength,omitempty"`
	ConnectedFrom string         `json:"connected_from,omitempty"`
}

type GraphNode struct {
	ID            string         `json:"id"`
	Content       string         `json:"content"`
	Metadata      map[string]any `json:"metadata,omitempty"`
	Source        string         `json:"source,omitempty"`
	Tags          []string       `json:"tags,omitempty"`
	Confidence    float64        `json:"confidence,omitempty"`
	Depth         int            `json:"depth"`
	Relationship  string         `json:"relationship,omitempty"`
	EdgeStrength  float64        `json:"edge_strength,omitempty"`
	ConnectedFrom string         `json:"connected_from,omitempty"`
	DirectionUsed string         `json:"direction_used,omitempty"`
}

type HealthOptions struct {
	// LiveEmbedder performs a real embedding API call if true. Costs
	// one provider token per run; defaults off so `ogham health` is free.
	LiveEmbedder bool
}

type HookOptions struct {
	Profile string
	DryRun  bool
}

type LinkUnlinkedOptions struct {
	BatchSize int
	Threshold float64
	MaxLinks  int
	Profile   string
}

type LinkUnlinkedResult struct {
	Status    string `json:"status"` // "linked" | "nothing_to_link"
	Profile   string `json:"profile"`
	Processed int    `json:"processed"`
	BatchSize int    `json:"batch_size"`
}

type LintCategory struct {
	Count  int              `json:"count"`
	Sample []map[string]any `json:"sample"`

	// OlderThanDays is non-zero only for stale_lifecycle (Python
	// includes this in its response so callers can see the threshold
	// they queried at).
	OlderThanDays int `json:"older_than_days,omitempty"`

	// Skipped is set on summary_drift when includeDrift=false so the
	// caller can tell "0 drift" from "we didn't check".
	Skipped bool `json:"skipped,omitempty"`
}

type LintReport struct {
	Profile        string       `json:"profile"`
	Healthy        bool         `json:"healthy"`
	IssueCount     int          `json:"issue_count"`
	Contradictions LintCategory `json:"contradictions"`
	Orphans        LintCategory `json:"orphans"`
	StaleLifecycle LintCategory `json:"stale_lifecycle"`
	StaleSummaries LintCategory `json:"stale_summaries"`
	SummaryDrift   LintCategory `json:"summary_drift"`
}

type LintWikiOptions struct {
	SampleSize   int  // default 10
	StableDays   int  // default 90
	IncludeDrift bool // default true (caller passes opts; LintWiki sets if zero-value)
	// contains filtered or unexported fields
}

type ListOptions struct {
	Limit  int
	Source string
	Tags   []string
	Before time.Time
	OnDate time.Time
}

type MaskedConfig struct {
	Profile   string            `json:"profile"`
	Database  MaskedDatabase    `json:"database"`
	Embedding MaskedEmbedding   `json:"embedding"`
	Paths     map[string]string `json:"paths"`
	// Warnings is a list of operator-facing diagnostics. Empty when the
	// config looks healthy. Currently flags configured-but-unprivileged
	// Supabase keys (anon / publishable) before the first request 401s.
	Warnings []string `json:"warnings,omitempty"`
}

type MaskedDatabase struct {
	Backend     string `json:"backend"`
	URL         string `json:"url,omitempty"`
	SupabaseURL string `json:"supabase_url,omitempty"`
	SupabaseKey string `json:"supabase_key,omitempty"`
	// SupabaseKeyKind reports the role behind the configured key:
	// "secret" / "service_role" (good), "anon" / "publishable" (bad,
	// will 401 on RPCs), or "unknown" (couldn't tell — try anyway).
	SupabaseKeyKind string `json:"supabase_key_kind,omitempty"`
}

type MaskedEmbedding struct {
	Provider  string `json:"provider"`
	Model     string `json:"model,omitempty"`
	Dimension int    `json:"dimension"`
	APIKey    string `json:"api_key,omitempty"`
}

type Memory struct {
	ID        string    `json:"id"`
	Content   string    `json:"content"`
	Tags      []string  `json:"tags"`
	Source    string    `json:"source,omitempty"`
	CreatedAt time.Time `json:"created_at"`
}

type ProfileCount struct {
	Profile string `json:"profile"`
	Count   int64  `json:"count"`
}

type ProfileTTL struct {
	Profile string `json:"profile"`
	TTLDays *int   `json:"ttl_days"`
}

type QueryTopicSummaryResult struct {
	Status         string `json:"status"`
	ID             string `json:"id,omitempty"`
	TopicKey       string `json:"topic_key"`
	Profile        string `json:"profile"`
	Version        int    `json:"version,omitempty"`
	StatusField    string `json:"summary_status,omitempty"` // fresh|stale|regenerating
	SourceCount    int    `json:"source_count,omitempty"`
	ModelUsed      string `json:"model_used,omitempty"`
	UpdatedAt      string `json:"updated_at,omitempty"`
	SourceHash     string `json:"source_hash,omitempty"`
	Level          string `json:"level,omitempty"`           // form actually returned
	RequestedLevel string `json:"requested_level,omitempty"` // what caller asked for (if differs from Level)
	Body           string `json:"body,omitempty"`            // selected text (one_line|short|body)
	Message        string `json:"message,omitempty"`         // populated for not_cached
}

type Report struct {
	OK       bool          `json:"ok"`
	Duration time.Duration `json:"duration_ns"`
	Backend  string        `json:"backend"`
	Provider string        `json:"provider,omitempty"`
	Checks   []CheckResult `json:"checks"`
}

type SearchOptions struct {
	Limit      int
	Tags       []string
	Source     string
	Profile    string // single-profile override; empty => use cfg.Profile
	Profiles   []string
	EntityTags []string
	// RecencyDecay > 0 tilts scoring toward newer memories. 0 = no decay.
	RecencyDecay float64
}

type SearchResult struct {
	ID          string         `json:"id"`
	Content     string         `json:"content"`
	Source      string         `json:"source,omitempty"`
	Profile     string         `json:"profile"`
	Tags        []string       `json:"tags"`
	Metadata    map[string]any `json:"metadata,omitempty"`
	Similarity  float64        `json:"similarity"`
	KeywordRank float64        `json:"keyword_rank"`
	Relevance   float64        `json:"relevance"`
	CreatedAt   time.Time      `json:"created_at"`
}

type Stage string

type StageReport struct {
	Profile         string `json:"profile"`
	FreshToStable   int    `json:"fresh_to_stable"`
	EditingClosed   int    `json:"editing_closed"`
	LifecycleAbsent bool   `json:"lifecycle_absent,omitempty"`
}

type Stats struct {
	Profile  string      `json:"profile"`
	Total    int64       `json:"total"`
	Sources  []Breakdown `json:"sources"`
	TopTags  []Breakdown `json:"top_tags"`
	Untagged int64       `json:"untagged_count"`
	WithTTL  int64       `json:"with_ttl_count"`
	Expiring int64       `json:"expiring_within_7d"`

	// ConnectedPct is the percentage (0-100) of active memories that
	// appear as either source_id or target_id in memory_relationships.
	// Answers "how much of my graph is wired up?" -- a profile at 5%
	// connected is effectively a flat list; one at 60%+ is a real graph.
	// When Total is 0 we return 0 (no rows, no percentage to compute).
	ConnectedPct float64 `json:"connected_pct"`

	// DecayCount is the number of active memories whose confidence has
	// fallen below DecayThreshold. Confidence decays over time in the
	// schema (see memories.confidence + the nightly decay job); memories
	// below the floor are nearly invisible to hybrid_search because the
	// relevance formula multiplies by confidence. Surfacing this as a
	// headline number lets operators spot profiles that need pruning or
	// reinforcement.
	DecayCount int64 `json:"decay_count"`
}

type StoreDecisionOptions struct {
	Decision        string
	Rationale       string
	Alternatives    []string
	ReasoningTrace  string
	Tags            []string
	RelatedMemories []string // rejected until Batch E lands
	Source          string
	Profile         string
}

type StoreEventOptions struct {
	Event        string
	When         string
	Participants []string
	Location     string
	Tags         []string
	Source       string
	Profile      string
}

type StoreFactOptions struct {
	Fact           string
	Subject        string
	Confidence     float64 // default 1.0; validated [0.0, 1.0]
	SourceCitation string
	Tags           []string
	Source         string
	Profile        string
}

type StoreOptions struct {
	Tags    []string
	Source  string
	Profile string // empty -> cfg.Profile (which itself falls back to "default")
	// Language is the 2-letter ISO code the extraction pipeline uses
	// for scoring, date parsing, and recurrence detection. Empty string
	// falls back to "en". Callers should set this from metadata[language]
	// on re-embed / migration paths, or leave it empty to default to
	// English. Values not in the embedded YAML registry produce a debug
	// slog warning and fall back silently to English.
	Language string
	// DryRun skips the actual DB write. Still runs extraction + embedding
	// + surprise so the caller sees what would happen. Useful for the
	// Day 4 --native-store-preview flag where we want to confirm the
	// pipeline is green without mutating the store.
	DryRun bool
	// Metadata is caller-supplied structured context that gets merged
	// over the extracted metadata (dates, etc.) before the DB write.
	// Primary consumer: the typed-store wrappers (store_decision,
	// store_fact, store_event, store_preference) which inject type-
	// specific structure. Extracted keys lose on collision so the
	// caller's intent wins. Nil is fine -- leaves extraction output
	// alone.
	//
	// If Metadata contains a "language" string key AND StoreOptions.Language
	// is empty, the metadata value is adopted as the effective language.
	// This mirrors Python's service.py behaviour where metadata carries
	// the language signal end-to-end.
	Metadata map[string]any
}

type StorePreferenceOptions struct {
	Preference   string
	Subject      string
	Alternatives []string
	Strength     string // "strong" | "normal" | "weak"; default "normal"
	Tags         []string
	Source       string
	Profile      string
}

type StoreResult struct {
	ID         string         `json:"id,omitempty"`
	Profile    string         `json:"profile"`
	Tags       []string       `json:"tags"`
	Entities   []string       `json:"entities"`
	Dates      []string       `json:"dates"`
	Importance float64        `json:"importance"`
	Surprise   float64        `json:"surprise"`
	LinkedTo   []AutoLink     `json:"linked_to,omitempty"`
	Elapsed    time.Duration  `json:"elapsed"`
	DryRun     bool           `json:"dry_run,omitempty"`
	Metadata   map[string]any `json:"metadata,omitempty"`
}

type SupabaseKeyKind string

type TLDRLevel string

type TopicSummary struct {
	ID           string    `json:"id"`
	TopicKey     string    `json:"topic_key"`
	ProfileID    string    `json:"profile"`
	Content      string    `json:"content"`
	TLDROneLine  *string   `json:"tldr_one_line,omitempty"`
	TLDRShort    *string   `json:"tldr_short,omitempty"`
	SourceCount  int       `json:"source_count"`
	SourceCursor *string   `json:"source_cursor,omitempty"`
	SourceHash   string    `json:"source_hash,omitempty"` // hex-encoded
	TokenCount   *int      `json:"token_count,omitempty"`
	Importance   float64   `json:"importance"`
	ModelUsed    string    `json:"model_used"`
	Version      int       `json:"version"`
	Status       string    `json:"status"`
	CreatedAt    time.Time `json:"created_at"`
	UpdatedAt    time.Time `json:"updated_at"`
	StaleReason  *string   `json:"stale_reason,omitempty"`
}

type UpdateOptions struct {
	Content  *string
	Tags     []string
	Metadata map[string]any
	// Profile override; empty -> cfg.Profile -> "default".
	Profile string
}

type UpdateResult struct {
	ID            string    `json:"id"`
	Profile       string    `json:"profile"`
	UpdatedAt     time.Time `json:"updated_at"`
	FieldsUpdated []string  `json:"fields_updated"`
	ReEmbedded    bool      `json:"re_embedded"`
}

type WalkKnowledgeOptions struct {
	// Depth is the maximum number of edges to traverse. Server clamps to
	// 0..5 (anything beyond explodes the rowset on dense profiles). 0
	// means "no walk" -- you'd just get the seed node back.
	Depth int

	// Direction is "outgoing", "incoming", or "both". Empty -> "both".
	Direction string

	// MinStrength filters edges by strength (0..1). Default 0.0 = keep all.
	MinStrength float64

	// RelationshipTypes optionally restricts to a set of relationship
	// labels (e.g. ["depends_on", "cites"]). Empty -> no filter.
	RelationshipTypes []string

	// Limit caps the result rowset. Default 50 mirrors Python.
	Limit int
}

type WalkKnowledgeResult struct {
	StartID   string      `json:"start_id"`
	Depth     int         `json:"depth"`
	Direction string      `json:"direction"`
	NodeCount int         `json:"node_count"`
	Nodes     []GraphNode `json:"nodes"`
}

type Zone string