yantrikdb 0.23.0

use serde::{Deserialize, Serialize};
use std::collections::HashMap;

// ── Embedder trait ──

/// Trait for converting text to embedding vectors.
/// Implementations can use any embedding model (sentence-transformers, candle, etc.).
pub trait Embedder: Send + Sync {
    /// Embed a single text string into a vector.
    fn embed(
        &self,
        text: &str,
    ) -> std::result::Result<Vec<f32>, Box<dyn std::error::Error + Send + Sync>>;

    /// Embed multiple texts. Default implementation calls embed() in a loop.
    fn embed_batch(
        &self,
        texts: &[&str],
    ) -> std::result::Result<Vec<Vec<f32>>, Box<dyn std::error::Error + Send + Sync>> {
        texts.iter().map(|t| self.embed(t)).collect()
    }

    /// The dimensionality of produced embeddings.
    fn dim(&self) -> usize;

    /// Stable identity of this embedder. SHA-256 of model weights, or
    /// equivalent fingerprint that distinguishes one model from another
    /// even when they share dim. Default `None` for back-compat with
    /// existing third-party Embedder impls.
    ///
    /// Used by `db.set_embedder*` (issue #41) to distinguish:
    /// - same-model-replacement (matching fingerprint, matching dim) — safe Arc swap
    /// - different-model-same-dim (different fingerprint, same dim) —
    ///   silent-corruption risk, rejected on populated `Known`-provenance
    ///   DBs with `ChangeEmbedderDigestRequiresReembed`
    ///
    /// Embedders returning `None` are treated as `ExternalOrUnknown`
    /// provenance — they may attach to empty or unknown-provenance DBs
    /// but cannot attach to a `Known`-provenance populated DB without
    /// going through `db.reembed()`. Conservative-correct: a custom
    /// embedder without identity cannot prove compatibility with
    /// previously-indexed vectors.
    ///
    /// Bundled embedders + the `set_embedder_named` named-download path
    /// override this with real fingerprints (SHA-256 from the embedder-
    /// download registry).
    fn fingerprint(&self) -> Option<String> {
        None
    }

    /// Human-readable name of this embedder (e.g. "potion-base-2M").
    /// Independent of fingerprint identity; used for observability and
    /// status reporting. Default `None` for back-compat. Named-download
    /// embedders override with the registry name.
    fn name(&self) -> Option<String> {
        None
    }
}

/// A memory record returned by get() and recall().
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Memory {
    pub rid: String,
    pub memory_type: String,
    pub text: String,
    pub created_at: f64,
    pub importance: f64,
    pub valence: f64,
    pub half_life: f64,
    pub last_access: f64,
    pub access_count: u32,
    pub consolidation_status: String,
    pub storage_tier: String,
    pub consolidated_into: Option<String>,
    pub metadata: serde_json::Value,
    pub namespace: String,
    // Cognitive dimensions (V10)
    pub certainty: f64,
    pub domain: String,
    pub source: String,
    pub emotional_state: Option<String>,
    // Session & temporal (V13)
    pub session_id: Option<String>,
    pub due_at: Option<f64>,
    pub temporal_kind: Option<String>,
}

/// Score breakdown for a recall result.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ScoreBreakdown {
    pub similarity: f64,
    pub decay: f64,
    pub recency: f64,
    pub importance: f64,
    pub graph_proximity: f64,
    /// Weighted contribution of each signal to the final score.
    pub contributions: ScoreContributions,
    /// Valence multiplier applied to the raw score.
    pub valence_multiplier: f64,
}

/// Weighted contributions of each signal (signal_value * weight).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ScoreContributions {
    pub similarity: f64,
    pub decay: f64,
    pub recency: f64,
    pub importance: f64,
    pub graph_proximity: f64,
}

/// **v0.10 Item 1 — typed temporal status (the status+flags algebra).**
///
/// `current_status` is EXCLUSIVE and chain-derived: a record either has a
/// selected active inbound Supersedes successor (`Superseded`) or it does
/// not (`Active`). Everything else — disputed, aged — is an ORTHOGONAL
/// flag, because those states co-occur with either status ("superseded AND
/// the successor is disputed" is exactly the situation an agent most needs
/// rendered honestly — consumer review). `#[non_exhaustive]` so
/// retracted/expired can join in v0.11+ without a breaking change.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum RecordStatus {
    #[default]
    Active,
    Superseded,
}

impl RecordStatus {
    pub fn as_str(&self) -> &'static str {
        match self {
            RecordStatus::Active => "active",
            RecordStatus::Superseded => "superseded",
        }
    }
}

/// Which mounted pack a recall hit came from (0.18). `None` for host rows.
///
/// Structured so consumers branch on fields instead of parsing the
/// `why_retrieved` prose stamp `pack:{name}` (kept for one release) — the
/// stamp carries the NAME, so two mounted versions of one pack were
/// indistinguishable, and a consumer keeping per-pack efficacy or lineage
/// had nothing to key on. `content_digest` is the manifest's digest as
/// mounted, so a hit can be attributed to the exact corpus bytes that
/// produced it even after the pack is rebuilt under the same id.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PackProvenance {
    /// `origin@version`, the mount id.
    pub pack_id: String,
    pub name: String,
    pub version: String,
    /// `"signed"` | `"unsigned"` | `"unverified"` — the trust tier the
    /// mount resolved to (the same word `mounted_packs()` reports).
    pub trust: String,
    /// The pack's `content_digest` as sealed, if the manifest carries one.
    pub content_digest: Option<String>,
}

/// A recall result with scoring information.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RecallResult {
    pub rid: String,
    pub memory_type: String,
    pub text: String,
    pub created_at: f64,
    pub importance: f64,
    pub valence: f64,
    pub score: f64,
    pub scores: ScoreBreakdown,
    pub why_retrieved: Vec<String>,
    pub metadata: serde_json::Value,
    pub namespace: String,
    // Cognitive dimensions (V10)
    pub certainty: f64,
    pub domain: String,
    pub source: String,
    pub emotional_state: Option<String>,
    // ── v0.10 Item 1: typed temporal status (status leads, prose follows;
    //    the why_retrieved prose stamps are retained for one release) ──
    /// Exclusive chain-derived status.
    #[serde(default)]
    pub current_status: RecordStatus,
    /// The rid of the selected successor when `current_status == Superseded`.
    #[serde(default)]
    pub superseded_by: Option<String>,
    /// Open-conflict counterpart rids (many-to-many; cleared on resolution).
    #[serde(default)]
    pub disputed_with: Vec<String>,
    /// Set when the record is aged-unconfirmed: the last time it was
    /// verified/updated. None = not aged.
    #[serde(default)]
    pub aged_last_verified: Option<f64>,
    /// Byte span `[start, end)` of `text` that the retrieval actually
    /// matched — the winning chunk window for records that entered via
    /// the vector index, or the best query-term window as a fallback.
    /// `None` when the whole text fits one embedder window (nothing to
    /// trim). Consumers use this to surface a snippet instead of the
    /// full text; the span is always aligned to `char` boundaries so
    /// slicing is safe.
    #[serde(default)]
    pub best_span: Option<(usize, usize)>,
    /// 0.18: set on rows that came from a mounted pack, `None` for host
    /// rows. See [`PackProvenance`].
    #[serde(default)]
    pub pack: Option<PackProvenance>,
    /// v48 (#149) valid time — when the described events happened, as
    /// opposed to `created_at` (when the row was written). `None` when
    /// the record carries no event time.
    ///
    /// Host rows carry the `memories` columns verbatim: those are what
    /// `event_after`/`event_before` range-scans, so a row's reported
    /// bounds can never claim an eligibility the filter denies. Pack
    /// rows, link-surfaced neighbors and `recall_as_of` rollback have no
    /// column to read and derive from metadata instead; none are subject
    /// to that filter.
    #[serde(default)]
    pub event_time_min: Option<f64>,
    #[serde(default)]
    pub event_time_max: Option<f64>,
}

/// v0.13.1 explain surface — per-lane status with the never-ran /
/// ran-found-nothing distinction made explicit (the ambiguous-zero
/// audit: `graph_proximity = 0.0` spent a release meaning both "the
/// lane found nothing" and "the lane never executed", and the two are
/// different facts with different remedies).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ExplainLaneReport {
    /// "ran" | "ran_empty" | "never_ran".
    pub status: String,
    /// Candidates this lane admitted or touched in this call.
    pub candidates: usize,
    /// For "never_ran": the precondition that kept it off (e.g.
    /// "expand_entities=false", "no query_text").
    pub reason: Option<String>,
}

/// One candidate of the explain pool. Every row carries the stable
/// `rid` — cross-run joins on text substrings are the fragility this
/// field retires.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ExplainPoolRow {
    pub rid: String,
    /// Final score at the snapshot, quantized at the engine's own
    /// ranking resolution (1e-6) — the exact value `rank_cmp` compares.
    pub score_q: f64,
    /// Raw cosine similarity (pre-fusion signal).
    pub similarity: f64,
    /// Per-query bm25 lexical strength in (0, 1]. `None` is
    /// CONDITIONAL and the lane block disambiguates it (finding-1
    /// rule: a bare null never stands alone): if
    /// `lanes["fts"].status == "ran"`, None means the FTS lane ran
    /// and did NOT match this candidate; if `"never_ran"` /
    /// `"ran_empty"`, no candidate has a strength and the lane's
    /// reason says why. A present value is always a real match —
    /// `Some(0.0)` is never emitted as a placeholder.
    pub lex: Option<f64>,
    /// The SET of lanes that admitted or lifted this candidate —
    /// explicitly separate from numeric contributions, because a zero
    /// contribution and a lane-that-never-admitted are different facts.
    pub lanes_admitted: Vec<String>,
    /// Rank within this pool by similarity alone (desc, rid asc) —
    /// "before fusion".
    pub rank_pre_fusion: usize,
    /// Rank in the pool's final comparator order — "after fusion".
    pub rank_post_fusion: usize,
    /// Whether this candidate survived MMR/truncation into the results.
    pub selected: bool,
}

/// Per-call retrieval-limit diagnostics. This distinguishes a small result
/// set caused by a small index from one caused by the engine inspecting a
/// bounded candidate pool.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct RetrievalLimits {
    pub requested_top_k: usize,
    pub requested_candidates: usize,
    pub candidate_cap: usize,
    pub fetch_k: usize,
    pub index_len: usize,
    pub has_post_filters: bool,
    pub cap_bound: bool,
}

/// v0.13.1 — the recall explain surface (co-iteration wheel 2, spec
/// locked with hermes 2026-08-06).
///
/// The load-bearing field is `pool`: the full candidate set snapshotted
/// **post-boost/post-reserve, pre-MMR-truncation** — the set that
/// ENTERS final selection. Snapshotted earlier it would show a healthy
/// vector lane and tell you nothing; later it would only show
/// survivors again. A user-side gate holding nothing but this surface
/// can detect admission-set instability across opens — the
/// eleventh-source class that no survivors-only view can see (a k=50
/// survivors comparison cleared a defect living at pool positions
/// 51–99).
///
/// Result rows do not repeat `lanes_admitted` — join them to `pool`
/// by `rid` (stable on both sides; that join is what the stable-rid
/// promotion exists for). The common-path caveat is deliberate: the
/// pool is the admission record, results are the selection record.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct RecallExplain {
    /// Exact HNSW candidate request and whether its safety ceiling bound.
    #[serde(default)]
    pub retrieval_limits: RetrievalLimits,
    /// The one ranking comparator (folded item: it no longer varies by
    /// site, so it is named once per response, not per row).
    pub comparator: String,
    /// How `score` is actually composed. Named here because the
    /// per-signal `contributions` are DIAGNOSTIC MAGNITUDES on mixed
    /// multiplicative/additive terms and do NOT sum to `score` —
    /// deriving arithmetic from them silently is the round-7 defect
    /// this field exists to refuse.
    pub score_algebra: String,
    /// Query sentiment driving valence multipliers; 0.0 means every
    /// `valence_multiplier` is 1.0 by construction, not by coincidence.
    pub query_sentiment: f64,
    /// **Denominator and threshold, stated** (the cross-gate name
    /// collision: two instruments published ~17×-apart numbers both
    /// called "degeneracy ratio"): this is the fraction of FTS-MATCHED
    /// CANDIDATES (the admitted set, not all matching sqlite rows)
    /// whose per-query normalized strength is >= 0.9 — i.e. within 10%
    /// of the query's best bm25 match, no rounding. Near 1.0 = bm25
    /// does not discriminate on this query and lexical strengths are
    /// ~flat. `None` is CONDITIONAL, not broken — exactly one of:
    /// the FTS lane never ran (`lanes["fts"].status == "never_ran"`,
    /// reason attached there) or it ran and matched nothing
    /// (`"ran_empty"`). The lane block is the disambiguator; a bare
    /// null never stands alone.
    pub bm25_near_best_fraction: Option<f64>,
    /// Per-lane status: vector / fts / claims / graph /
    /// importance_fallback / pack.
    pub lanes: std::collections::BTreeMap<String, ExplainLaneReport>,
    /// The candidate pool in comparator order at the snapshot boundary.
    pub pool: Vec<ExplainPoolRow>,
}

/// Response from recall with confidence and hints for interactive retrieval.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RecallResponse {
    pub results: Vec<RecallResult>,
    pub confidence: f64,
    /// Human-readable explanation of what drove the confidence score.
    pub certainty_reasons: Vec<String>,
    pub retrieval_summary: RetrievalSummary,
    pub hints: Vec<RefinementHint>,
    /// v0.10 Item 1b (trace T08): typed coverage of what was searched
    /// and why the result set looks the way it does. serde(default) so
    /// pre-v0.10 serialized responses still deserialize.
    #[serde(default)]
    pub coverage: SearchCoverage,
    /// Exact HNSW candidate request and whether its safety ceiling bound.
    #[serde(default)]
    pub retrieval_limits: RetrievalLimits,
}

/// Summary of how retrieval was performed.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RetrievalSummary {
    pub top_similarity: f64,
    pub score_spread: f64,
    pub sources_used: Vec<String>,
    pub candidate_count: usize,
}

/// v0.10 Item 1b — trace T08 "absence-with-coverage". Typed statement
/// of the search scope and outcome, so a consumer can distinguish "the
/// substrate has nothing in this scope" from "candidates exist but none
/// cleared the relevance gate" WITHOUT parsing certainty_reasons prose.
/// nuron's false-retry loop (T08 fixture) came from exactly that
/// ambiguity: an empty result read as a transient failure, so the agent
/// retried a query that could never succeed.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SearchCoverage {
    /// Namespace scope searched (`None` = all namespaces).
    pub namespace: Option<String>,
    /// Memory-type scope searched (`None` = all types).
    pub memory_type: Option<String>,
    /// Records in scope after filters — the candidate universe, not the
    /// HNSW pool.
    pub candidate_count: usize,
    /// The relevance gate consulted for the outcome: the per-database
    /// learned `gate_tau` (similarity level where importance boosting
    /// engages — the engine's own notion of "relevant enough").
    pub threshold_tau: f64,
    /// Top similarity among returned results (0.0 when empty).
    pub top_similarity: f64,
    /// The typed T08 distinction.
    pub outcome: CoverageOutcome,
    /// v0.10 Item 2 — the piggyback label request (nuron's labeling
    /// economics): at most 2 served rids the learner would most like
    /// graded (nearest the relevance gate, never previously asked for
    /// this query). Rides on a response the consumer already requested;
    /// grading is one token each (relevant/irrelevant via
    /// recall_feedback / reject_recalled), skipping is free and the
    /// same (query, rid) is never re-asked. Empty when there is nothing
    /// informative to ask.
    #[serde(default)]
    pub label_request: Vec<String>,
}

impl Default for SearchCoverage {
    fn default() -> Self {
        Self {
            namespace: None,
            memory_type: None,
            candidate_count: 0,
            threshold_tau: 0.0,
            top_similarity: 0.0,
            outcome: CoverageOutcome::NoMatchingRecord,
            label_request: Vec::new(),
        }
    }
}

/// v0.10 Item 1b — why a recall's result set looks the way it does.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum CoverageOutcome {
    /// Results returned and the best of them clears the relevance gate.
    Matched,
    /// Candidates exist in scope, but nothing returned clears the gate
    /// (or nothing was returned at all). These are guesses, not
    /// knowledge — retrying the same query will not improve them.
    BelowThreshold,
    /// The searched scope contains no records. There is nothing to
    /// find; do not retry.
    NoMatchingRecord,
}

/// A hint for refining a query when confidence is low.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RefinementHint {
    pub hint_type: String,
    pub suggestion: String,
    pub related_entities: Vec<String>,
}

/// An edge in the entity graph.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Edge {
    pub edge_id: String,
    pub src: String,
    pub dst: String,
    pub rel_type: String,
    pub weight: f64,
}

/// An entity in the knowledge graph.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Entity {
    pub name: String,
    pub entity_type: String,
    pub first_seen: f64,
    pub last_seen: f64,
    pub mention_count: i64,
}

/// Per-rank outcome coverage for caller-side organization rollups.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct RollupRankOutcomeStats {
    pub rank: usize,
    pub impressions: i64,
    pub expanded_impressions: i64,
    pub finalized_impressions: i64,
    pub finalized_returned_children: i64,
    pub finalized_selected_children: i64,
    pub finalized_corrected_children: i64,
    pub explicit_child_selection_rate: Option<f64>,
}

/// Read-only telemetry report for deciding whether rollup outcomes are ready
/// for an offline evaluation. This does not authorize production learning.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct RollupOutcomeReport {
    pub namespace: Option<String>,
    pub since: Option<f64>,
    pub total_impressions: i64,
    pub distinct_queries: i64,
    pub distinct_rollups: i64,
    pub expanded_impressions: i64,
    pub finalized_impressions: i64,
    pub finalized_distinct_queries: i64,
    pub finalized_distinct_rollups: i64,
    pub finalized_returned_children: i64,
    pub finalized_selected_children: i64,
    pub finalized_corrected_children: i64,
    pub explicitly_unselected_children: i64,
    pub expansion_rate: Option<f64>,
    pub telemetry_completion_rate: Option<f64>,
    pub explicit_child_selection_rate: Option<f64>,
    pub max_finalized_query_share: Option<f64>,
    pub max_finalized_rollup_share: Option<f64>,
    pub per_rank: Vec<RollupRankOutcomeStats>,
    /// `no_data`, `insufficient_evidence`, or
    /// `ready_for_offline_evaluation`.
    pub evidence_status: String,
    pub readiness_failures: Vec<String>,
}

/// One immutable, finalized child example from the rollup outcome ledger.
/// Query text and mutable memory features are deliberately excluded.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct RollupOutcomeExample {
    pub export_schema_version: u32,
    pub impression_id: String,
    pub query_hash: String,
    pub namespace: String,
    pub rollup_rid: String,
    pub rollup_rank: usize,
    pub rollup_score: f64,
    pub child_rid: String,
    pub child_rank: usize,
    pub returned_child_count: usize,
    pub selected: bool,
    pub corrected: bool,
    pub created_at: f64,
    pub outcome_finalized_at: f64,
}

/// Coverage for explicit false-negative labels. This is deliberately separate
/// from [`RollupOutcomeReport`], whose readiness only governs pruning returned
/// children.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct RollupMembershipReport {
    pub namespace: Option<String>,
    pub since: Option<f64>,
    pub total_impressions: i64,
    pub expanded_impressions: i64,
    pub finalized_impressions: i64,
    pub finalized_added_children: i64,
    pub finalized_impressions_with_additions: i64,
    pub finalized_distinct_queries_with_additions: i64,
    pub telemetry_completion_rate: Option<f64>,
    pub added_child_rate: Option<f64>,
    /// `no_data`, `insufficient_evidence`, or
    /// `ready_for_offline_evaluation`.
    pub evidence_status: String,
    pub readiness_failures: Vec<String>,
}

/// One child from a finalized membership example. Returned and omitted
/// positives share an impression group but remain distinct classes.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct RollupMembershipExample {
    pub export_schema_version: u32,
    pub impression_id: String,
    /// Namespace-scoped linkage key. It is not an anonymization boundary.
    pub query_key: String,
    pub namespace: String,
    pub rollup_rid: String,
    pub rollup_rank: usize,
    pub rollup_score: f64,
    pub requested_count: Option<usize>,
    pub query_shape: Option<String>,
    pub child_rid: String,
    pub child_rank: Option<usize>,
    pub child_score: Option<f64>,
    pub returned_child_count: usize,
    pub returned: bool,
    pub omitted_positive: bool,
    pub positive: bool,
    pub corrected: bool,
    pub omission_source: Option<String>,
    pub impression_created_at: f64,
    pub outcome_finalized_at: f64,
}

/// Engine statistics.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Stats {
    pub active_memories: i64,
    pub consolidated_memories: i64,
    pub tombstoned_memories: i64,
    pub archived_memories: i64,
    pub edges: i64,
    pub entities: i64,
    pub operations: i64,
    pub open_conflicts: i64,
    pub resolved_conflicts: i64,
    pub pending_triggers: i64,
    pub active_patterns: i64,
    pub scoring_cache_entries: usize,
    pub vec_index_entries: usize,
    pub graph_index_entities: usize,
    pub graph_index_edges: usize,
    // v0.10 Item 1: status-led read path adoption surface. All
    // serde(default) so pre-v0.10 serialized stats still deserialize.
    /// `"exclude_superseded"` (status-led read path active) or
    /// `"legacy"` (include-everything; pre-v0.10 DB that hasn't opted in).
    #[serde(default)]
    pub status_read_policy: String,
    /// Records currently superseded (selected active inbound
    /// `supersedes` edge). Global — link identity is namespace-checked
    /// at creation, so no per-namespace filter applies here.
    #[serde(default)]
    pub superseded_records: i64,
    /// Adoption nudge: superseded results actually served since engine
    /// boot (only possible on legacy policy or `include_superseded`
    /// calls). Non-zero on a legacy DB means the status read policy
    /// would have excluded stale facts — consider
    /// `set_status_read_policy(true)`.
    #[serde(default)]
    pub superseded_served_since_boot: u64,
    /// Maximum oversampled HNSW candidate pool used by ordinary recall.
    /// A caller asking for more than this many final results raises the
    /// effective ceiling to `top_k`, so requested results are never clipped.
    #[serde(default)]
    pub recall_candidate_cap: usize,
    /// Maximum number of distinct named namespaces retained in the
    /// since-boot recall-cap telemetry map. Cross-namespace calls (`"*"`)
    /// and the bounded overflow bucket (`"<other>"`) are reserved separately.
    #[serde(default)]
    pub recall_candidate_cap_namespace_capacity: usize,
    /// Recalls since boot where the candidate ceiling reduced the HNSW pool
    /// that would otherwise have been inspected. Non-zero means a retrieval
    /// quality limit bound and deserves review for the workload in question.
    #[serde(default)]
    pub recall_candidate_cap_bound_since_boot: u64,
    /// Same counter grouped by recall namespace. `"*"` means the call
    /// searched across namespaces (`namespace=None`).
    #[serde(default)]
    pub recall_candidate_cap_bound_by_namespace_since_boot: HashMap<String, u64>,
    /// True once more distinct namespaces bound the candidate cap than the
    /// telemetry map can retain. Additional namespaces are counted under
    /// `"<other>"`; the global total remains exact.
    #[serde(default)]
    pub recall_candidate_cap_namespace_stats_truncated_since_boot: bool,
    /// Maximum verified synthesis generations one evidence record may back
    /// through local admission. Replication remains convergence-first and may
    /// surface a remote over-cap state in the counters below.
    #[serde(default)]
    pub synthesis_fanout_cap: usize,
    /// Local synthesis admissions refused at the fan-out boundary since open.
    #[serde(default)]
    pub synthesis_fanout_refused_since_boot: u64,
    /// Largest current verified-synthesis fan-out of any evidence record.
    #[serde(default)]
    pub synthesis_fanout_current_high_water: usize,
    /// Evidence records whose current verified fan-out exactly equals the cap.
    #[serde(default)]
    pub synthesis_fanout_sources_at_cap: i64,
    /// Evidence records above the local cap, possible only through replication
    /// or a later explicit cap reduction. Non-zero requires operator review.
    #[serde(default)]
    pub synthesis_fanout_sources_over_cap: i64,
    /// **v0.10 Item 4a.4** — active anti-laundering gate mode
    /// (`off` | `warn` | `enforce`).
    #[serde(default)]
    pub provenance_gate_mode: String,
    /// **v0.10 Item 4a.4 — adoption nudge.** Writes the gate FLAGGED as
    /// internally inconsistent but did not refuse (warn mode) since boot.
    /// Non-zero on a migrated DB means `enforce` would reject those writes —
    /// consider `set_provenance_gate_mode(Enforce)` once callers are fixed.
    #[serde(default)]
    pub provenance_flagged_since_boot: u64,
    /// Claim-chain gate mode (`off` | `shadow` | `enforce`); see
    /// `engine::claims_lane`. Every install defaults to `shadow`.
    #[serde(default)]
    pub claim_chain_gate_mode: String,
    /// Since boot: claims-lane admissions and traversals the gate would
    /// refuse under `enforce`, keyed `hop1:<reason>` / `seed:<reason>` /
    /// `hop2:<reason>` (reasons: ungrounded, not_yet_valid, superseded,
    /// negated, non_asserted). Under `shadow` they were still admitted;
    /// under `enforce` they were dropped. Empty under `off`.
    #[serde(default)]
    pub claim_chain_gate_suppressed_since_boot: HashMap<String, u64>,
    /// **Issue #225** — second-SQLite-library guard mode (`off` | `warn` |
    /// `refuse`); every install defaults to `refuse`.
    #[serde(default)]
    pub foreign_sqlite_mode: String,
    /// Whether this platform/store can be scanned (Linux, file-backed).
    #[serde(default)]
    pub foreign_sqlite_supported: bool,
    /// The last scan found another SQLite library holding the store open in
    /// this process. Under `refuse`, writes are failing right now.
    #[serde(default)]
    pub foreign_sqlite_active: bool,
    /// A foreign instance was seen at some point since this engine opened.
    /// Latched: its close may have unlinked the shm/WAL under the engine,
    /// so writes stay refused (under `refuse`) until the engine is reopened.
    #[serde(default)]
    pub foreign_sqlite_tainted: bool,
    /// Scans since boot that found a foreign instance.
    #[serde(default)]
    pub foreign_sqlite_detected_since_boot: u64,
    /// Engine writes refused (pre-checks and aborted commits) since boot.
    #[serde(default)]
    pub foreign_sqlite_refused_since_boot: u64,
    /// Commits that reached the store without going through this engine
    /// (another process, most likely) since boot; each queues an integrity
    /// check.
    #[serde(default)]
    pub foreign_commits_detected_since_boot: u64,
    /// A queued integrity check has not run yet.
    #[serde(default)]
    pub integrity_check_pending: bool,
    #[serde(default)]
    pub integrity_checks_since_boot: u64,
    /// The last `PRAGMA quick_check` result, empty until one has run.
    #[serde(default)]
    pub last_integrity_check: String,
    /// Non-tombstoned records carrying an explicit, caller-supplied
    /// `metadata.provenance_verified = true` marker. This is an audit signal,
    /// not an engine assertion: the engine cannot reconstruct authorship.
    #[serde(default)]
    pub provenance_verified_records: i64,
    /// Non-tombstoned `source = "user"` records without the explicit marker.
    /// These are unknown, not presumed wrong; migrated databases can use this
    /// count to distinguish legacy attribution from newly verified writes.
    #[serde(default)]
    pub unverified_user_source_records: i64,
    /// Non-tombstoned records grouped by their declared source label.
    #[serde(default)]
    pub provenance_source_counts: HashMap<String, i64>,
    /// Non-tombstoned records grouped by `metadata.provenance_method`.
    /// Missing, empty, or malformed metadata is reported as `unmarked`.
    #[serde(default)]
    pub provenance_method_counts: HashMap<String, i64>,
    /// Records without `metadata.provenance_verified = true`, grouped by
    /// declared source. This identifies which integration needs an audit;
    /// it does not presume that unverified legacy records are incorrect.
    #[serde(default)]
    pub unverified_source_counts: HashMap<String, i64>,
    /// Detected embedder input window in characters, or `None` if the
    /// probe has not run (`detect_embedder_window()`) or found no
    /// truncation. Text beyond it is stored but never embedded.
    #[serde(default)]
    pub embedder_window_chars: Option<usize>,
    /// Writes since boot whose text exceeded that window — records
    /// stored intact but indexed from their head only, so their tails
    /// are unfindable. Non-zero means retrieval is losing content.
    #[serde(default)]
    pub embedder_truncated_writes: u64,
    /// Writes since boot whose overflow was covered by chunk vectors
    /// instead (window known ⇒ the text was split, each window embedded
    /// and indexed, retrieval collapses to the record). Handled, not
    /// lost — the counterpart to `embedder_truncated_writes`.
    #[serde(default)]
    pub embedder_chunked_writes: u64,
    /// Durable chunk (window) vectors currently stored in
    /// `memory_chunks`. Explains why `vec_index_entries` can exceed the
    /// record count on a corpus with long records.
    #[serde(default)]
    pub chunk_vectors: u64,
    /// C5b pollution census: entities whose name contains an apostrophe
    /// — phantom possessives (`Pranab's`) and contraction entities
    /// (`Don't`) minted by the pre-C5a tokenizer. Production measured
    /// 748 mentions stranded on one phantom; this count is the
    /// migration's before/after success metric.
    #[serde(default)]
    pub apostrophe_entities: u64,
    /// Alias rows written by the possessive migration (reversible fold
    /// of phantom entities into their canonicals at index build).
    #[serde(default)]
    pub possessive_aliases: u64,
}

/// A proactive trigger.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Trigger {
    pub trigger_type: String,
    pub reason: String,
    pub urgency: f64,
    pub source_rids: Vec<String>,
    pub suggested_action: String,
    pub context: HashMap<String, serde_json::Value>,
}

/// Consolidation result (after consolidation runs).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ConsolidationResult {
    pub consolidated_rid: String,
    pub source_rids: Vec<String>,
    pub cluster_size: usize,
    pub summary: String,
    pub importance: f64,
    pub entities_linked: usize,
}

/// Dry run consolidation preview.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ConsolidationPreview {
    pub cluster_size: usize,
    pub texts: Vec<String>,
    pub preview_summary: String,
    pub source_rids: Vec<String>,
}

/// Internal struct with embedding data for clustering.
#[derive(Debug, Clone)]
pub struct MemoryWithEmbedding {
    pub rid: String,
    pub memory_type: String,
    pub text: String,
    pub embedding: Vec<f32>,
    pub created_at: f64,
    pub importance: f64,
    pub valence: f64,
    pub half_life: f64,
    pub last_access: f64,
    pub metadata: serde_json::Value,
    pub namespace: String,
}

/// A decayed memory candidate from decay().
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DecayedMemory {
    pub rid: String,
    pub text: String,
    pub memory_type: String,
    pub original_importance: f64,
    pub current_score: f64,
    pub days_since_access: f64,
}

/// One engine-grounded source observed when a synthesized memory is admitted.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub(crate) struct SynthesisDependency {
    pub source_rid: String,
    pub source_revision_num: i64,
    pub is_direct: bool,
}

/// Typed lifecycle descriptor committed atomically with a synthesized memory.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub(crate) struct SynthesisAdmission {
    pub axis: String,
    pub granularity: String,
    pub logical_key: String,
    pub evidence_version: String,
    pub dependencies: Vec<SynthesisDependency>,
}

/// Lightweight scoring fields cached in memory for fast recall scoring.
/// These are the only fields needed to compute composite_score() during recall.
#[derive(Debug, Clone)]
pub struct ScoringRow {
    pub created_at: f64,
    pub importance: f64,
    pub half_life: f64,
    pub last_access: f64,
    pub access_count: u32,
    pub valence: f64,
    pub consolidation_status: String,
    /// NULL for ordinary memories; synthesized rows are eligible only when
    /// this is exactly `verified`.
    pub synthesis_state: Option<String>,
    /// Query-facing representation labels for verified synthesized rows.
    /// Ordinary memories leave both fields NULL and retain their legacy rank.
    pub synthesis_axis: Option<String>,
    pub synthesis_granularity: Option<String>,
    pub memory_type: String,
    pub namespace: String,
    // Cognitive dimensions (V10)
    pub certainty: f64,
    pub domain: String,
    pub source: String,
    pub emotional_state: Option<String>,
}

/// Input for batch record operations.
#[derive(Debug, Clone)]
pub struct RecordInput {
    pub text: String,
    pub memory_type: String,
    pub importance: f64,
    pub valence: f64,
    pub half_life: f64,
    pub metadata: serde_json::Value,
    pub embedding: Vec<f32>,
    pub namespace: String,
    // Cognitive dimensions (V10)
    pub certainty: f64,
    pub domain: String,
    pub source: String,
    pub emotional_state: Option<String>,
    /// v0.10 4a.6d-2b: per-item idempotency key, same contract and scope as
    /// `record_with_idempotency` — (origin_actor, normalized namespace, key),
    /// digest variant `Record` (the caller-supplied embedding is part of the
    /// payload). `None` = unkeyed item. A key that already committed with the
    /// SAME payload makes this item an idempotent hit (its position in the
    /// returned rids carries the ORIGINAL rid; the item writes nothing);
    /// the same key with a DIFFERENT payload fails the WHOLE batch with a
    /// typed `IdempotencyConflict` — batches stay all-or-nothing on failure.
    pub idempotency_key: Option<String>,
    /// Caller-supplied event time in epoch seconds (historical import).
    /// `None` = the engine stamps `now()` — byte-for-byte the pre-field
    /// behavior. When `Some`, the value lands in `created_at`, `updated_at`,
    /// AND `last_access` (an imported record was last touched at its event
    /// time, so decay runs from then, not from the import), feeds the
    /// replicated op payload verbatim, participates in the idempotency
    /// digest (a re-dated write is a different write — payload_digest docs),
    /// and makes `recall_as_of`/`time_window` meaningful on bulk-loaded
    /// corpora. Precedent: `record_with_rid`'s `created_at_unix_micros` has
    /// always been caller-supplied on the replication path.
    pub created_at: Option<f64>,
}

// ── Conflict types (V2) ──

/// The type of semantic conflict between two memories.
#[derive(Debug, Clone, PartialEq)]
pub enum ConflictType {
    IdentityFact,
    Preference,
    Temporal,
    Consolidation,
    Minor,
}

impl ConflictType {
    pub fn as_str(&self) -> &'static str {
        match self {
            ConflictType::IdentityFact => "identity_fact",
            ConflictType::Preference => "preference",
            ConflictType::Temporal => "temporal",
            ConflictType::Consolidation => "consolidation",
            ConflictType::Minor => "minor",
        }
    }

    pub fn from_str(s: &str) -> Self {
        match s {
            "identity_fact" => ConflictType::IdentityFact,
            "preference" => ConflictType::Preference,
            "temporal" => ConflictType::Temporal,
            "consolidation" => ConflictType::Consolidation,
            _ => ConflictType::Minor,
        }
    }

    pub fn default_priority(&self) -> &'static str {
        match self {
            ConflictType::IdentityFact => "critical",
            ConflictType::Preference => "high",
            ConflictType::Temporal => "high",
            ConflictType::Consolidation => "medium",
            ConflictType::Minor => "low",
        }
    }
}

/// A conflict between two memories.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Conflict {
    pub conflict_id: String,
    pub conflict_type: String,
    pub priority: String,
    pub status: String,
    pub memory_a: String,
    pub memory_b: String,
    pub entity: Option<String>,
    pub rel_type: Option<String>,
    pub detected_at: f64,
    pub detected_by: String,
    pub detection_reason: String,
    pub resolved_at: Option<f64>,
    pub resolved_by: Option<String>,
    pub strategy: Option<String>,
    pub winner_rid: Option<String>,
    pub resolution_note: Option<String>,
}

/// Result of a conflict resolution.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ConflictResolutionResult {
    pub conflict_id: String,
    pub strategy: String,
    pub winner_rid: Option<String>,
    pub loser_tombstoned: bool,
    pub new_memory_rid: Option<String>,
}

/// Result of a user-initiated correction.
///
/// **Issue #47 (v0.7.20):** `correct()` now mutates the memory in place,
/// preserving `rid` and `created_at`. `original_rid` and `corrected_rid`
/// are therefore always equal; `original_tombstoned` is always `false`.
/// The fields are kept for back-compat with v0.7.19-and-earlier consumers
/// that destructured this struct. `revision_num` is new — it tells the
/// caller which revision number the correction wrote (1-indexed,
/// monotonically increasing per-rid).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CorrectionResult {
    pub original_rid: String,
    pub corrected_rid: String,
    pub original_tombstoned: bool,
    pub revision_num: i64,
}

/// A single entry from a `correct()` revision history query.
/// See `YantrikDB::history()`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RecordRevision {
    pub revision_id: String,
    pub rid: String,
    pub revision_num: i64,
    pub prior_text: String,
    pub prior_metadata: serde_json::Value,
    pub prior_importance: f64,
    pub prior_valence: f64,
    pub reason: String,
    pub applied_at: f64,
    pub origin_actor: String,
    /// v0.10 Item 3: the prior embedding's provenance, present only when
    /// this revision came from a text-changing (re-embedding) correction.
    /// `prior_embedding_model` is the model that produced the prior vector
    /// (may be `None` if the original write didn't stamp one);
    /// `prior_embedding_hash` is a lowercase-hex fingerprint of the prior
    /// vector, so a consumer can see the retrieval vector changed and a
    /// replica can verify it applied the same bytes.
    #[serde(default)]
    pub prior_embedding_model: Option<String>,
    #[serde(default)]
    pub prior_embedding_hash: Option<String>,
}

// ── Issue #48 — record-to-record link model (schema v31) ──

/// Closed set of record-to-record link types + a `Custom` escape hatch.
///
/// See docs/record_link_model_rfc.md. The recall-time proximity polarity
/// (whether surfacing one endpoint should boost or demote the other) is a
/// pure function of the variant — see [`LinkType::recall_polarity`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum LinkType {
    /// This record builds on / improves the target (newer is better).
    Advances,
    /// This record replaces the target. Does NOT auto-tombstone the
    /// target (semantic claim, not a lifecycle action). Recall demotes
    /// the superseded predecessor.
    Supersedes,
    /// This record disagrees with the target. Quasi-symmetric — queried
    /// bidirectionally.
    Contradicts,
    /// This record provides evidence for the target.
    Supports,
    /// This record raises a question about the target.
    Questions,
    /// This record was derived from / inspired by the target (provenance,
    /// no correctness claim — distinct from Advances).
    DerivedFrom,
    /// Extensibility hatch. Stored as `custom:<name>`; engine does not
    /// interpret the name (treated as a weak positive at recall time).
    Custom(String),
}

/// How a link affects recall when traversing from one endpoint to the
/// other. Multiplier applied to the graph-proximity contribution of the
/// linked record; <1.0 demotes, >0 with <1 dampens, 1.0 is neutral-positive.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct LinkRecallPolarity {
    /// Multiplier for the LINKED (target/other-endpoint) record's
    /// proximity contribution.
    pub neighbor_factor: f64,
    /// Multiplier applied to the SEED record's own score when it is the
    /// target of this link type (used by Supersedes to demote a
    /// superseded predecessor). 1.0 = no self-demotion.
    pub demote_self_as_target: f64,
}

impl LinkType {
    /// Serialize to the canonical string stored in `record_links.link_type`.
    pub fn as_str(&self) -> String {
        match self {
            LinkType::Advances => "advances".to_string(),
            LinkType::Supersedes => "supersedes".to_string(),
            LinkType::Contradicts => "contradicts".to_string(),
            LinkType::Supports => "supports".to_string(),
            LinkType::Questions => "questions".to_string(),
            LinkType::DerivedFrom => "derived_from".to_string(),
            LinkType::Custom(name) => format!("custom:{name}"),
        }
    }

    /// Parse from the stored string. `custom:<name>` round-trips to
    /// `Custom(name)`; any other unrecognized string also becomes
    /// `Custom(...)` so forward-compat strings from a newer node don't
    /// hard-error on an older one.
    pub fn from_str_lenient(s: &str) -> LinkType {
        match s {
            "advances" => LinkType::Advances,
            "supersedes" => LinkType::Supersedes,
            "contradicts" => LinkType::Contradicts,
            "supports" => LinkType::Supports,
            "questions" => LinkType::Questions,
            "derived_from" => LinkType::DerivedFrom,
            other => {
                let name = other.strip_prefix("custom:").unwrap_or(other);
                LinkType::Custom(name.to_string())
            }
        }
    }

    /// Whether this link type is treated as undirected at traversal /
    /// recall time. Only `Contradicts` is symmetric.
    pub fn is_symmetric(&self) -> bool {
        matches!(self, LinkType::Contradicts)
    }

    /// Recall-time polarity. Pure function of the variant. See the
    /// relation-aware-scoring table in the RFC.
    pub fn recall_polarity(&self) -> LinkRecallPolarity {
        match self {
            // Positive: pull the neighbor in at full proximity.
            LinkType::Supports | LinkType::Advances => LinkRecallPolarity {
                neighbor_factor: 1.0,
                demote_self_as_target: 1.0,
            },
            // Provenance: weaker positive.
            LinkType::DerivedFrom => LinkRecallPolarity {
                neighbor_factor: 0.6,
                demote_self_as_target: 1.0,
            },
            // Supersedes: boost the successor (neighbor) AND demote the
            // superseded predecessor when IT is the surfaced record.
            LinkType::Supersedes => LinkRecallPolarity {
                neighbor_factor: 1.0,
                demote_self_as_target: 0.5,
            },
            // Relevant-but-not-endorsing: surface the contradictor so the
            // caller sees the conflict, but no positive relevance halo.
            LinkType::Contradicts => LinkRecallPolarity {
                neighbor_factor: 0.3,
                demote_self_as_target: 1.0,
            },
            // Weak relevance / uncertainty.
            LinkType::Questions => LinkRecallPolarity {
                neighbor_factor: 0.3,
                demote_self_as_target: 1.0,
            },
            // Engine doesn't interpret custom — weak positive.
            LinkType::Custom(_) => LinkRecallPolarity {
                neighbor_factor: 0.5,
                demote_self_as_target: 1.0,
            },
        }
    }
}

/// A record-to-record link to create alongside (or after) a record write.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RecordLink {
    pub target_rid: String,
    pub link_type: LinkType,
}

/// Direction filter for [`YantrikDB::linked_records`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LinkDirection {
    Outbound,
    Inbound,
    Both,
}

/// A single result from a `linked_records` traversal.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LinkedRecord {
    pub rid: String,
    pub link_type: String,
    pub created_at: f64,
    /// "outbound" or "inbound" relative to the queried rid.
    pub direction: String,
}

/// Per-link outcome from `record_with_links_partial` (issue #48). The
/// record always commits first (durable via the oplog); each link is
/// then attempted independently — a `Failed` on one does not abort the
/// others or fail the call. Callers get the rid + a full per-link vec.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum LinkResult {
    /// Link row was newly inserted.
    Inserted {
        target_rid: String,
        link_type: String,
    },
    /// Link already existed (UNIQUE(source,target,type) hit; INSERT OR
    /// IGNORE was a no-op). Retry-safe; algo treats it like `Inserted`
    /// but it's distinguished for telemetry.
    AlreadyExists {
        target_rid: String,
        link_type: String,
    },
    /// Link insert failed; the record itself is still durable.
    Failed {
        target_rid: String,
        link_type: String,
        error: String,
    },
}

/// Result of [`YantrikDB::audit_leak_candidates`] (issue #48 follow-up).
///
/// Replaces the broken "orphan" metric (memories lacking oplog presence),
/// which the trader postmortem proved is a benign **oplog-compaction
/// artifact**, not a leak: locally-originated memories whose oplog rows
/// aged out of the retention window look orphan-shaped but are healthy.
///
/// The windowed check only flags memories created *within* the surviving
/// oplog window (`created_at >= window_floor`, where `window_floor =
/// MIN(oplog.timestamp)`) that nonetheless have no oplog op and no
/// `replication_apply_log` entry. Inside the window the oplog row SHOULD
/// still exist, so its absence is a genuine signal (write-path bug /
/// direct-SQL injection). Outside the window, absence is expected
/// compaction and is NOT counted.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LeakAuditReport {
    /// `MIN(oplog.timestamp)` — the compaction boundary. `None` if the
    /// oplog is empty (no window can be established; `candidate_count` 0).
    pub window_floor: Option<f64>,
    /// Exact count of in-window leak candidates.
    pub candidate_count: usize,
    /// Up to `max_rids` candidate rids (the count is exact; this is a
    /// bounded sample for investigation).
    pub candidate_rids: Vec<String>,
}

/// One active verified synthesis whose evidence no longer satisfies the
/// admission invariants. Reasons are stable machine-readable strings with
/// source-specific context appended after `:`.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct SynthesisEvidenceAuditIssue {
    pub synthesis_rid: String,
    pub reasons: Vec<String>,
}

/// Read-only integrity report for evidence-versioned synthesis records.
/// `candidate_count` is exact; `issues` is a bounded diagnostic sample.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct SynthesisEvidenceAuditReport {
    pub verified_active_count: usize,
    pub candidate_count: usize,
    pub orphan_dependency_count: usize,
    pub sources_over_fanout_cap: usize,
    pub dependency_cycle_count: usize,
    pub duplicate_logical_key_group_count: usize,
    pub issues: Vec<SynthesisEvidenceAuditIssue>,
}

// ── Cognition types (V3) ──

/// Trigger type classification.
#[derive(Debug, Clone, PartialEq)]
pub enum TriggerType {
    DecayReview,
    ConsolidationReady,
    ConflictEscalation,
    TemporalDrift,
    Redundancy,
    RelationshipInsight,
    ValenceTrend,
    EntityAnomaly,
    PatternDiscovered,
}

impl TriggerType {
    pub fn as_str(&self) -> &'static str {
        match self {
            TriggerType::DecayReview => "decay_review",
            TriggerType::ConsolidationReady => "consolidation_ready",
            TriggerType::ConflictEscalation => "conflict_escalation",
            TriggerType::TemporalDrift => "temporal_drift",
            TriggerType::Redundancy => "redundancy",
            TriggerType::RelationshipInsight => "relationship_insight",
            TriggerType::ValenceTrend => "valence_trend",
            TriggerType::EntityAnomaly => "entity_anomaly",
            TriggerType::PatternDiscovered => "pattern_discovered",
        }
    }

    pub fn from_str(s: &str) -> Self {
        match s {
            "decay_review" => TriggerType::DecayReview,
            "consolidation_ready" => TriggerType::ConsolidationReady,
            "conflict_escalation" => TriggerType::ConflictEscalation,
            "temporal_drift" => TriggerType::TemporalDrift,
            "redundancy" => TriggerType::Redundancy,
            "relationship_insight" => TriggerType::RelationshipInsight,
            "valence_trend" => TriggerType::ValenceTrend,
            "entity_anomaly" => TriggerType::EntityAnomaly,
            "pattern_discovered" => TriggerType::PatternDiscovered,
            _ => TriggerType::DecayReview,
        }
    }

    pub fn default_cooldown_secs(&self) -> f64 {
        match self {
            TriggerType::DecayReview => 86400.0 * 3.0,
            TriggerType::ConsolidationReady => 86400.0,
            TriggerType::ConflictEscalation => 86400.0 * 2.0,
            TriggerType::TemporalDrift => 86400.0 * 14.0,
            TriggerType::Redundancy => 86400.0,
            TriggerType::RelationshipInsight => 86400.0 * 7.0,
            TriggerType::ValenceTrend => 86400.0 * 7.0,
            TriggerType::EntityAnomaly => 86400.0 * 7.0,
            TriggerType::PatternDiscovered => 86400.0 * 7.0,
        }
    }

    pub fn default_expiry_secs(&self) -> f64 {
        match self {
            TriggerType::DecayReview => 86400.0 * 7.0,
            TriggerType::ConsolidationReady => 86400.0 * 3.0,
            TriggerType::ConflictEscalation => 86400.0 * 14.0,
            _ => 86400.0 * 7.0,
        }
    }
}

/// Configuration for the think() cognition loop.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ThinkConfig {
    pub importance_threshold: f64,
    pub decay_threshold: f64,
    pub max_triggers: usize,
    pub run_consolidation: bool,
    pub run_conflict_scan: bool,
    pub run_pattern_mining: bool,
    pub consolidation_sim_threshold: f64,
    pub consolidation_time_window_days: f64,
    pub consolidation_min_cluster: usize,
    pub consolidation_limit: usize,
    /// When true, consolidation requires candidate pairs to share at least one
    /// extracted entity (falls back to cosine-only when either side has no
    /// entities). Guards against merging semantically similar sentences that
    /// refer to different subjects.
    pub consolidation_require_entity_overlap: bool,
    pub min_active_memories: i64,
    pub run_personality: bool,
    /// **v0.7.23 prototype.** When true, `think()` extracts simple
    /// "<subject> is <value>" assertions from free-text memories into the
    /// claim layer so `scan_claim_conflicts` can detect attribute-value
    /// updates made via plain `record()` (e.g. "brand color is blue" →
    /// "brand color is now green"). Off by default — opt-in because the
    /// copular heuristic can flag non-exclusive values for review. Skipped
    /// when encryption is enabled (stored text is ciphertext).
    pub extract_attribute_claims: bool,
}

impl Default for ThinkConfig {
    fn default() -> Self {
        Self {
            importance_threshold: 0.5,
            decay_threshold: 0.1,
            max_triggers: 10,
            run_consolidation: true,
            run_conflict_scan: true,
            run_pattern_mining: false,
            consolidation_sim_threshold: 0.6,
            consolidation_time_window_days: 7.0,
            consolidation_min_cluster: 2,
            consolidation_limit: 5,
            consolidation_require_entity_overlap: true,
            min_active_memories: 10,
            run_personality: true,
            extract_attribute_claims: false,
        }
    }
}

/// Result of a think() pass.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ThinkResult {
    pub triggers: Vec<Trigger>,
    pub consolidation_count: usize,
    pub conflicts_found: usize,
    pub patterns_new: usize,
    pub patterns_updated: usize,
    pub expired_triggers: usize,
    pub personality_updated: bool,
    pub duration_ms: u64,
}

/// A persisted trigger with lifecycle state.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PersistedTrigger {
    pub trigger_id: String,
    pub trigger_type: String,
    pub urgency: f64,
    pub status: String,
    pub reason: String,
    pub suggested_action: String,
    pub source_rids: Vec<String>,
    pub context: serde_json::Value,
    pub created_at: f64,
    pub delivered_at: Option<f64>,
    pub acknowledged_at: Option<f64>,
    pub acted_at: Option<f64>,
    pub expires_at: Option<f64>,
}

/// A detected pattern across memories.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Pattern {
    pub pattern_id: String,
    pub pattern_type: String,
    pub status: String,
    pub confidence: f64,
    pub description: String,
    pub evidence_rids: Vec<String>,
    pub entity_names: Vec<String>,
    pub context: serde_json::Value,
    pub first_seen: f64,
    pub last_confirmed: f64,
    pub occurrence_count: i64,
}

/// Result of pattern mining.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PatternMiningResult {
    pub new_patterns: usize,
    pub updated_patterns: usize,
    pub stale_patterns: usize,
}

/// Configuration for pattern mining.
#[derive(Debug, Clone)]
pub struct PatternConfig {
    pub co_occurrence_min_count: usize,
    pub temporal_cluster_min_events: usize,
    pub valence_trend_delta_threshold: f64,
    pub topic_cluster_sim_threshold: f64,
    pub topic_cluster_time_window_days: f64,
    pub entity_hub_min_degree: usize,
    pub max_patterns: usize,
    // Cross-domain mining (V13)
    pub cross_domain_candidates_per_domain: usize,
    pub cross_domain_sim_threshold: f64,
    pub cross_domain_max_per_pair: usize,
    pub entity_bridge_min_domains: usize,
    pub entity_bridge_min_mentions_per_domain: usize,
    pub run_cross_domain: bool,
}

// ── Profiling types (feature-gated) ──

/// Timing breakdown for a single recall() invocation.
#[cfg(feature = "profiling")]
#[derive(Debug, Clone)]
pub struct RecallTimings {
    pub vec_search_ms: f64,
    pub cache_score_ms: f64,
    pub fetch_ms: f64,
    pub scoring_ms: f64,
    pub graph_ms: f64,
    pub reinforce_ms: f64,
    pub sort_truncate_ms: f64,
    pub total_ms: f64,
    pub candidate_count: usize,
    pub graph_expansion_count: usize,
}

/// Result of recall_profiled() — recall results plus timing breakdown.
#[cfg(feature = "profiling")]
#[derive(Debug, Clone)]
pub struct RecallProfiledResult {
    pub results: Vec<RecallResult>,
    pub timings: RecallTimings,
}

/// Builder for composable recall queries.
///
/// ```rust,ignore
/// let results = db.query(embedding)
///     .top_k(10)
///     .memory_type("episodic")
///     .namespace("work")
///     .expand_entities("tell me about Alice")
///     .time_window(start, end)
///     .execute()?;
/// ```
#[derive(Debug, Clone)]
pub struct RecallQuery {
    pub embedding: Vec<f32>,
    pub top_k: usize,
    pub time_window: Option<(f64, f64)>,
    pub memory_type: Option<String>,
    pub include_consolidated: bool,
    pub expand_entities: bool,
    pub query_text: Option<String>,
    pub skip_reinforce: bool,
    pub namespace: Option<String>,
    // V10 filters
    pub domain: Option<String>,
    pub source: Option<String>,
    // Issue #46: confidence first-class on recall.
    pub certainty_min: Option<f64>,
    pub order: Option<String>,
    // v0.10 Item 1: re-admit superseded records (stamped) for
    // history/archaeology queries. No-op on legacy-policy databases.
    pub include_superseded: bool,
}

impl RecallQuery {
    /// Create a new query builder with the given embedding vector.
    pub fn new(embedding: Vec<f32>) -> Self {
        Self {
            embedding,
            top_k: 10,
            time_window: None,
            memory_type: None,
            include_consolidated: false,
            expand_entities: false,
            query_text: None,
            skip_reinforce: false,
            namespace: None,
            domain: None,
            source: None,
            certainty_min: None,
            order: None,
            include_superseded: false,
        }
    }

    /// v0.10 Item 1: include superseded records in results (stamped
    /// with `current_status = Superseded` + `superseded_by`) instead of
    /// excluding them under the status read policy. For "show me what I
    /// used to believe" archaeology queries.
    pub fn include_superseded(mut self) -> Self {
        self.include_superseded = true;
        self
    }

    /// Issue #46: drop results whose certainty falls below `min`.
    pub fn certainty_min(mut self, min: f64) -> Self {
        self.certainty_min = Some(min);
        self
    }

    /// Issue #46: re-sort the top_k by `"relevance"` (default),
    /// `"certainty"`, or `"recency"`. Invalid strings surface as
    /// `YantrikDbError::InvalidInput` on `execute()`.
    pub fn order(mut self, order: &str) -> Self {
        self.order = Some(order.to_string());
        self
    }

    /// Set maximum number of results to return.
    pub fn top_k(mut self, k: usize) -> Self {
        self.top_k = k;
        self
    }

    /// Filter by memory type (e.g., "episodic", "semantic", "procedural").
    pub fn memory_type(mut self, mt: &str) -> Self {
        self.memory_type = Some(mt.to_string());
        self
    }

    /// Filter by namespace.
    pub fn namespace(mut self, ns: &str) -> Self {
        self.namespace = Some(ns.to_string());
        self
    }

    /// Restrict results to a time window (created_at between start and end).
    pub fn time_window(mut self, start: f64, end: f64) -> Self {
        self.time_window = Some((start, end));
        self
    }

    /// Enable graph expansion with the given query text for entity extraction.
    pub fn expand_entities(mut self, query_text: &str) -> Self {
        self.expand_entities = true;
        self.query_text = Some(query_text.to_string());
        self
    }

    /// Include consolidated (merged) memories in results.
    pub fn include_consolidated(mut self) -> Self {
        self.include_consolidated = true;
        self
    }

    /// Skip spaced-repetition reinforcement on accessed memories.
    pub fn skip_reinforce(mut self) -> Self {
        self.skip_reinforce = true;
        self
    }

    /// Filter by domain (e.g., "work", "health", "family").
    pub fn domain(mut self, d: &str) -> Self {
        self.domain = Some(d.to_string());
        self
    }

    /// Filter by source (e.g., "user", "system", "document", "inference").
    pub fn source(mut self, s: &str) -> Self {
        self.source = Some(s.to_string());
        self
    }
}

/// Learned scoring weights stored per-database for adaptive recall.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LearnedWeights {
    pub w_sim: f64,
    pub w_decay: f64,
    pub w_recency: f64,
    pub gate_tau: f64,
    pub alpha_imp: f64,
    pub keyword_boost: f64,
    pub generation: i64,
}

impl Default for LearnedWeights {
    fn default() -> Self {
        Self {
            w_sim: 0.50,
            w_decay: 0.20,
            w_recency: 0.30,
            gate_tau: 0.25,
            alpha_imp: 0.80,
            keyword_boost: 0.31,
            generation: 0,
        }
    }
}

impl LearnedWeights {
    /// Force every weight into a sane range.
    ///
    /// **Weights arrive from the database, and the database is not a trusted
    /// oracle.** They are written by the online-learning loop, but a row can
    /// also be edited by hand, restored from an old schema, corrupted, or
    /// carried across a version that meant something different by the same
    /// column. Until 2026-08-13 they were loaded and used verbatim: a
    /// `keyword_boost` of 50 would have made the lexical side-boost dwarf
    /// every semantic score in the store, and the only symptom would be
    /// "recall got strange".
    ///
    /// `keyword_boost` is the one that most needs this. It is applied as an
    /// ADDITIVE term (lexical evidence deliberately counts for more when
    /// cosine is weak), so unlike the multiplicative priors it has no
    /// similarity-relative ceiling of its own — its bound has to come from
    /// here.
    ///
    /// Clamping rather than rejecting is deliberate: a database must still
    /// open with a bad weights row. The values are a tuning artifact, not
    /// user data, so the safe response is to fall back into range and carry
    /// on rather than refuse to serve recall.
    pub fn clamped(mut self) -> Self {
        let fix = |v: f64, lo: f64, hi: f64, fallback: f64| {
            if v.is_finite() {
                v.clamp(lo, hi)
            } else {
                fallback
            }
        };
        let d = Self::default();
        self.w_sim = fix(self.w_sim, 0.05, 1.0, d.w_sim);
        self.w_decay = fix(self.w_decay, 0.0, 1.0, d.w_decay);
        self.w_recency = fix(self.w_recency, 0.0, 1.0, d.w_recency);
        // Below ~0.05 the importance gate opens for everything; above ~0.9
        // it never opens at all.
        self.gate_tau = fix(self.gate_tau, 0.05, 0.90, d.gate_tau);
        // The policy budget already caps what importance can DO; this keeps
        // the weight itself interpretable.
        self.alpha_imp = fix(self.alpha_imp, 0.0, 1.5, d.alpha_imp);
        // Hard ceiling: at 1.0 a perfect lexical match is worth as much as a
        // perfect semantic one, which is the most it can defensibly mean.
        self.keyword_boost = fix(self.keyword_boost, 0.0, 1.0, d.keyword_boost);
        self
    }
}

// ── Personality types (V11) ──

/// A single personality trait with its current score and derivation metadata.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PersonalityTrait {
    pub trait_name: String,
    pub score: f64,
    pub confidence: f64,
    pub sample_count: i64,
    pub updated_at: f64,
}

/// Aggregated personality profile across all traits.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PersonalityProfile {
    pub traits: Vec<PersonalityTrait>,
    pub updated_at: f64,
}

// ── Session types (V13) ──

/// A session tracks a conversation or interaction period.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Session {
    pub session_id: String,
    pub namespace: String,
    pub client_id: String,
    pub status: String,
    pub started_at: f64,
    pub ended_at: Option<f64>,
    pub summary: Option<String>,
    pub avg_valence: Option<f64>,
    pub memory_count: i64,
    pub topics: Vec<String>,
    pub metadata: serde_json::Value,
}

/// Summary returned when ending a session.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SessionSummary {
    pub session_id: String,
    pub duration_secs: f64,
    pub memory_count: i64,
    pub avg_valence: f64,
    pub topics: Vec<String>,
}

// ── Temporal & Entity Profile types (V13) ──

/// Rich profile of an entity across time, domains, and sessions.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EntityProfile {
    pub entity: String,
    pub entity_type: String,
    pub mention_count: i64,
    pub session_count: i64,
    pub domains: Vec<DomainCount>,
    pub avg_valence: f64,
    pub valence_trend: f64,
    pub dominant_emotion: Option<String>,
    pub interaction_frequency: f64,
    pub last_mentioned_at: f64,
    pub first_seen: f64,
    pub window_days: f64,
}

/// Count of mentions within a domain.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DomainCount {
    pub domain: String,
    pub count: i64,
}

// ── Cross-domain mining types (V13) ──

/// A link between memories in different domains discovered by cross-domain mining.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CrossDomainLink {
    pub rid_a: String,
    pub rid_b: String,
    pub domain_a: String,
    pub domain_b: String,
    pub similarity: f64,
    pub text_a: String,
    pub text_b: String,
    pub score: f64,
}

/// An entity that bridges multiple domains.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EntityBridge {
    pub entity: String,
    pub domains: Vec<DomainCount>,
    pub bridge_score: f64,
    pub total_mentions: i64,
}

// ── Relationship depth types (V14) ──

/// Rich interaction metrics for an entity, measuring depth of knowledge.
/// This goes beyond simple mention counts to capture how deeply the system
/// knows about an entity across sessions, domains, and time.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RelationshipDepth {
    /// The entity name.
    pub entity: String,
    /// The entity type (person, organization, tech, etc.).
    pub entity_type: String,
    /// Number of distinct sessions where this entity appeared.
    pub sessions_together: i64,
    /// Total memories mentioning this entity.
    pub memories_mentioning: i64,
    /// Average valence of memories involving this entity.
    pub avg_valence: f64,
    /// Domains this entity spans (e.g., ["work", "health", "family"]).
    pub domains_spanning: Vec<String>,
    /// Distinct relationship types connected to this entity.
    pub relationship_types: Vec<String>,
    /// Number of distinct entities this entity is connected to in the graph.
    pub connection_count: i64,
    /// Composite depth score (0.0-1.0): higher = deeper relationship.
    /// Combines sessions, memories, domain breadth, connection count.
    pub depth_score: f64,
    /// When this entity was first seen.
    pub first_seen: f64,
    /// When this entity was last seen.
    pub last_seen: f64,
    /// Mentions per day since first seen.
    pub interaction_frequency: f64,
}

// ── Substitution categories (V14) ──

/// A substitution category (e.g., "databases", "cloud_providers").
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SubstitutionCategory {
    pub id: String,
    pub name: String,
    pub conflict_mode: String,
    pub status: String,
    pub member_count: i64,
}

/// A member of a substitution category.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SubstitutionMember {
    pub id: String,
    pub category_name: String,
    pub token_normalized: String,
    pub token_display: String,
    pub confidence: f64,
    pub source: String,
    pub status: String,
}

/// Result of reclassifying a conflict (learning entry point).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ReclassifyResult {
    pub conflict_id: String,
    pub old_type: String,
    pub new_type: String,
    pub learned_members: Vec<LearnedMember>,
    pub category_created: Option<String>,
}

/// A member learned during conflict reclassification.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LearnedMember {
    pub token: String,
    pub category_name: String,
    pub is_new: bool,
}

impl Default for PatternConfig {
    fn default() -> Self {
        Self {
            co_occurrence_min_count: 3,
            temporal_cluster_min_events: 3,
            valence_trend_delta_threshold: 0.3,
            topic_cluster_sim_threshold: 0.55,
            topic_cluster_time_window_days: 30.0,
            entity_hub_min_degree: 5,
            max_patterns: 50,
            cross_domain_candidates_per_domain: 15,
            cross_domain_sim_threshold: 0.50,
            cross_domain_max_per_pair: 3,
            entity_bridge_min_domains: 2,
            entity_bridge_min_mentions_per_domain: 3,
            run_cross_domain: true,
        }
    }
}