Backend(Embedder& embedder, const std::string& db_path = "");

/// DB-only constructor — no embedder required.

/// readonly=true: opens with SQLITE_OPEN_READONLY, skips schema creation (for export).

/// readonly=false (default): opens read-write and creates users/settings tables.

explicit Backend(const std::string& db_path, bool readonly = false);

~Backend() override;

/// Path to the database file.

std::string db_path() const override;

/// Store text with metadata. Returns memory ID.

std::string store(const std::string& text, json metadata = {},

bool defer_embedding = false) override;

/// Store a Level 5 RAG document chunk.

int store_document(const DocumentChunk& chunk,

bool defer_embedding = false) override;

/// Store / finalize a raw L1 conversation turn (turns table).

int store_turn(const std::string& user_text,

const std::string& assistant_text,

const std::string& model_name = "",

bool defer_embedding = false,

const std::string& session_guid = "",

const std::string& source_timestamp = "",

const std::string& session_name = "",

const std::string& name_source = "") override;

std::vector<TurnRecord> turns_by_session(

const std::string& session_guid) override;

bool finalize_turn(int turn_id,

const std::string& assistant_text,

const std::string& model_name = "") override;

/// Write back a document's embedding (import path).

bool update_document_embedding(int document_id,

const std::vector<float>& emb) override;

/// Store a curated L6 decision/lesson. Returns decision_id.

int store_decision(const std::string& text,

const std::string& status = "current",

const std::string& tags = "",

const std::string& source_timestamp = "",

bool defer_embedding = false) override;

KnowledgeResult store_knowledge(const KnowledgeInput& in) override;

json find_document_source(const std::string& path) override;

json list_document_sources() override;

void invalidate_all_caches() override;

json delete_document_source(int document_source_id) override;

/// Agent API Phase 2 reads (see StorageBackend docs).

std::vector<AgentHit> agent_search(const AgentSearchQuery& q) override;

json agent_get(const AgentGetQuery& q) override;

/// Agent API Phase 4: timeline / curation / review (see StorageBackend docs).

json agent_timeline(const TimelineQuery& q) override;

json agent_update(const UpdateRequest& req) override;

json agent_review(const std::string& action,

const std::vector<std::string>& ids) override;

/// Near-duplicate decision hints for free text (Phase 3 note surface).

std::vector<std::pair<int,float>> possible_supersedes_for_text(

const std::string& text) override;

/// Write back a single row's embedding for any embedded context table.

bool update_decision_embedding(int decision_id,

const std::vector<float>& emb) override;

bool update_turn_embedding(int turn_id,

const std::vector<float>& emb) override;

bool note_exists_exact(const std::string& text,

const std::string& created_at) override;

bool decision_exists_exact(const std::string& text,

const std::string& created_at) override;

bool turn_exists_fuzzy(const std::string& user_text,

const std::string& ts,

int window_seconds) override;

std::optional<TurnRecord> find_turn_by_text(

const std::string& user_text) override;

bool update_turn_meta(int turn_id,

const std::string& timestamp = "",

const std::string& session_guid = "") override;

std::vector<std::string> current_decisions(int limit) override;

bool set_decision_status(int decision_id, const std::string& status) override;

std::vector<std::string> decisions_by_status(const std::string& status, int limit) override;

std::vector<TurnRecord> unsummarized_turns(int limit = 0) override;

// --- v0.12.0 turn_id-based turn-summary methods (schema migration) ---

bool turn_summary_exists(int turn_id) override;

bool finalize_turn_summary(int turn_id, const std::string& text,

const std::string& summary_model_name) override;

bool mark_turn_summarized(int turn_id, const std::string& model_name) override;

int reset_abandoned_turn_summaries(int limit = 0) override;

std::string last_episode_end(const std::string& session_guid) override;

std::vector<SummaryRecord> l2_summaries_since(

const std::string& session_guid, const std::string& since_ts) override;

std::vector<EpisodeCandidateTurn> episode_candidate_turns(

const std::string& session_guid, const std::string& since_ts) override;

int store_episode_close(const EpisodeClose& close) override;

std::vector<std::string> episodes_needing_close(int idle_minutes) override;

std::vector<TurnRecord> turns_by_session_desc(

const std::string& session_guid, int limit = 0) override;

std::vector<SummaryRecord> turn_summaries_by_session_desc(

const std::string& session_guid, int limit = 0) override;

std::vector<SummaryRecord> episodes_by_session_desc(

const std::string& session_guid, int limit = 0) override;

// PHASE8: update_text is gone (text is never rewritten in place).

/// Hybrid search across the four corpora: vector cosine blended with the

/// custom terms-index keyword relevance. (`collections` is currently a

/// no-op; kept for API compat.)

SearchResponse search(const std::string& query,

int limit = 5,

float min_score = 0.0f,

std::vector<std::string> collections = {}) override;

/// Text-only fallback: FTS5 keyword + phonetic scoring, no embeddings.

SearchResponse search_text_only(const std::string& query,

int limit = 5) override;

/// Number of stored memories.

int count() const override;

std::vector<std::pair<std::string, int64_t>> table_row_counts() const override;

/// True if any table holds a non-NULL embedding.

bool has_embeddings() const override;

/// Total rows across the four embedded tables (rebuild scope).

int count_embeddable_rows(const std::string& table = "all") const override;

/// Load all memories. Returns vector of SearchResult (score=0).

std::vector<SearchResult> load_all(const std::string& collection = "") override;

/// Rebuild embeddings for all stored documents. Returns doc count.

int rebuild_embeddings(Embedder& embedder, bool progress = true,

const std::string& table = "all") override;

void set_embedder(Embedder& embedder) override;

void set_vector_type(vector_codec::VectorType t) override;

int backfill_embeddings(Embedder& embedder,

const std::string& table = "all") override;

uint8_t embedding_version() const override;

uint8_t increment_embedding_version() override;

int reindex_table(const std::string& table, bool progress = false) override;

void reset_terms_table() override;

/// Get distinct collection names.

std::vector<std::string> collections() const override;

/// Delete a memory by ID. Returns true if deleted.

bool delete_memory(int memory_id) override;

/// Delete multiple memories by ID. Returns count deleted.

int delete_batch(const std::vector<int>& memory_ids) override;

/// Search by metadata field matching with optional temporal filtering. Returns vector of results.

std::vector<SearchResult> search_by_metadata(const json& metadata_filter, int limit = 0,

const std::string& after = "",

const std::string& before = "") override;

void close() override;

/// Delete old conversation entries older than specified hours. Returns count deleted.

int cleanup_old_conversations(float max_age_hours) override;

// --- Users / settings ---

std::optional<UserInfo> get_user_by_username(const std::string& username) override;

std::optional<std::string> get_user_password(const std::string& username) override;

void update_user_token(const std::string& username, const std::string& new_hash) override;

int create_user(const std::string& username, const std::string& token_hash) override;

bool delete_user(const std::string& username) override;

void set_user_password(const std::string& username, const std::string& password_hash) override;

std::optional<UserInfo> get_user_by_token_hash(const std::string& token_hash) override;

std::optional<std::string> get_setting(const std::string& key) override;

void set_setting(const std::string& key, const std::string& value) override;

// --- Schema introspection ---

std::vector<SchemaObject> list_schema_objects() override;

std::vector<std::string> table_column_names(const std::string& table) override;

void iterate_table_rows(const std::string& table,

const std::function<void(const ExportRow&)>& cb) override;

struct Impl;

std::unique_ptr<Impl> pImpl;