Struct Database 

pub struct Database { /* private fields */ }

Implementations

impl Database

pub fn log_audit_event( &self, kind: &str, actor: &str, action: &str, target: Option<&str>, status: &str, detail: Option<&str>, ) -> Result<i64, MicroClawError>

pub fn verify_audit_chain(&self) -> Result<AuditChainStatus, MicroClawError>

Verify the tamper-evident audit hash chain. Walks all sealed entries in id order, checking that each links to the previous (prev_hash) and that its entry_hash still matches its content. Returns the first break, if any. Unsealed legacy rows (NULL entry_hash) are ignored.

pub fn list_audit_logs( &self, kind: Option<&str>, limit: usize, ) -> Result<Vec<AuditLogRecord>, MicroClawError>

pub fn count_audit_events_since( &self, kind: &str, since: &str, ) -> Result<i64, MicroClawError>

Count audit-chain events of one kind recorded at or after since.

impl Database

pub fn upsert_auth_password_hash( &self, password_hash: &str, ) -> Result<(), MicroClawError>

pub fn get_auth_password_hash(&self) -> Result<Option<String>, MicroClawError>

pub fn clear_auth_password_hash(&self) -> Result<bool, MicroClawError>

pub fn create_auth_session( &self, session_id: &str, label: Option<&str>, expires_at: &str, ) -> Result<(), MicroClawError>

pub fn validate_auth_session( &self, session_id: &str, ) -> Result<bool, MicroClawError>

pub fn revoke_auth_session( &self, session_id: &str, ) -> Result<bool, MicroClawError>

pub fn revoke_all_auth_sessions(&self) -> Result<usize, MicroClawError>

pub fn create_api_key( &self, label: &str, key_hash: &str, prefix: &str, scopes: &[String], expires_at: Option<&str>, rotated_from_key_id: Option<i64>, ) -> Result<i64, MicroClawError>

pub fn list_api_keys(&self) -> Result<Vec<AuthApiKeyRecord>, MicroClawError>

pub fn rotate_api_key_revoke_old( &self, old_key_id: i64, ) -> Result<bool, MicroClawError>

pub fn revoke_api_key(&self, key_id: i64) -> Result<bool, MicroClawError>

pub fn validate_api_key_hash( &self, key_hash: &str, ) -> Result<Option<(i64, Vec<String>)>, MicroClawError>

impl Database

pub fn upsert_chat( &self, chat_id: i64, chat_title: Option<&str>, chat_type: &str, ) -> Result<(), MicroClawError>

pub fn resolve_or_create_chat_id( &self, channel: &str, external_chat_id: &str, chat_title: Option<&str>, chat_type: &str, ) -> Result<i64, MicroClawError>

pub fn find_chat_id( &self, channel: &str, external_chat_id: &str, ) -> Result<Option<i64>, MicroClawError>

pub fn store_message(&self, msg: &StoredMessage) -> Result<(), MicroClawError>

pub fn store_message_if_new( &self, msg: &StoredMessage, ) -> Result<bool, MicroClawError>

pub fn message_exists( &self, chat_id: i64, message_id: &str, ) -> Result<bool, MicroClawError>

pub fn get_recent_messages( &self, chat_id: i64, limit: usize, ) -> Result<Vec<StoredMessage>, MicroClawError>

pub fn get_all_messages( &self, chat_id: i64, ) -> Result<Vec<StoredMessage>, MicroClawError>

pub fn get_chats_by_type( &self, chat_type: &str, limit: usize, ) -> Result<Vec<ChatSummary>, MicroClawError>

pub fn get_recent_chats( &self, limit: usize, ) -> Result<Vec<ChatSummary>, MicroClawError>

pub fn get_chat_type( &self, chat_id: i64, ) -> Result<Option<String>, MicroClawError>

pub fn get_chat_id_by_channel_and_title( &self, channel: &str, chat_title: &str, ) -> Result<Option<i64>, MicroClawError>

pub fn get_chat_channel( &self, chat_id: i64, ) -> Result<Option<String>, MicroClawError>

pub fn get_chat_external_id( &self, chat_id: i64, ) -> Result<Option<String>, MicroClawError>

pub fn get_messages_since_last_bot_response( &self, chat_id: i64, max: usize, fallback: usize, ) -> Result<Vec<StoredMessage>, MicroClawError>

Get messages since the bot’s last response in this chat. Falls back to fallback_limit most recent messages if bot never responded.

pub fn clear_chat_context(&self, chat_id: i64) -> Result<bool, MicroClawError>

Clear all resettable chat state without deleting chat metadata or memories. This removes resumable session state, historical messages, and scheduled task state.

pub fn clear_chat_conversation( &self, chat_id: i64, ) -> Result<bool, MicroClawError>

Clear conversational context for a chat while preserving scheduled task state. This removes resumable session state and historical messages only.

pub fn delete_chat_data(&self, chat_id: i64) -> Result<bool, MicroClawError>

pub fn get_new_user_messages_since( &self, chat_id: i64, since: &str, ) -> Result<Vec<StoredMessage>, MicroClawError>

pub fn get_messages_since( &self, chat_id: i64, since: &str, limit: usize, ) -> Result<Vec<StoredMessage>, MicroClawError>

pub fn search_messages_fts( &self, query: &str, chat_id: Option<i64>, since: Option<&str>, limit: usize, ) -> Result<Vec<StoredMessage>, MicroClawError>

Full-text search over stored messages using the SQLite FTS5 index.

query must be a valid FTS5 match expression (simple words are OK, e.g. "rust async"). Returns ranked matches newest-first for equally-ranked rows. When chat_id is Some, the search is scoped to that chat; otherwise it spans all chats. When since is Some, only messages with timestamp >= that value are returned. Results are truncated to limit rows.

pub fn count_messages_for_chat( &self, chat_id: i64, ) -> Result<i64, MicroClawError>

Total number of stored messages in a chat (both sides). Used as a cheap proxy for how well the bot “knows” this person.

pub fn get_active_chat_ids_since( &self, since: &str, ) -> Result<Vec<i64>, MicroClawError>

pub fn list_idle_chats( &self, cutoff: &str, limit: usize, ) -> Result<Vec<i64>, MicroClawError>

Chats whose most recent message is older than cutoff (i.e. idle since then). Only chats that have ever had a message are returned.

impl Database

pub fn upsert_goal_state( &self, goal_id: &str, chat_id: i64, objective: &str, status: &str, constraints_json: Option<&str>, progress_json: Option<&str>, budget_json: Option<&str>, ) -> Result<(), MicroClawError>

pub fn get_active_goal_state( &self, chat_id: i64, ) -> Result<Option<GoalStateRecord>, MicroClawError>

pub fn start_experience_run( &self, run_id: &str, goal_id: Option<&str>, chat_id: i64, channel: &str, run_kind: &str, objective: &str, environment_fingerprint: Option<&str>, ) -> Result<(), MicroClawError>

pub fn finish_experience_run( &self, run_id: &str, status: &str, result_summary: Option<&str>, duration_ms: i64, ) -> Result<(), MicroClawError>

pub fn update_experience_metrics( &self, run_id: &str, input_tokens: i64, output_tokens: i64, llm_requests: i64, tool_calls: i64, tool_errors: i64, estimated_cost_usd: Option<f64>, ) -> Result<(), MicroClawError>

pub fn recover_running_experience_runs(&self) -> Result<usize, MicroClawError>

Retire experience rows left running by a previous process. The restart signal is retained for observability but intentionally uses a non-governing verifier type because a process crash is not evidence that an activated skill was incorrect.

pub fn latest_experience_run_id( &self, chat_id: i64, ) -> Result<Option<String>, MicroClawError>

pub fn experience_run_belongs_to_chat( &self, run_id: &str, chat_id: i64, ) -> Result<bool, MicroClawError>

pub fn get_recent_experience_runs( &self, chat_id: Option<i64>, limit: usize, ) -> Result<Vec<ExperienceRunRecord>, MicroClawError>

pub fn record_experience_retrievals( &self, querying_run_id: &str, selections: &[(String, String, f64)], ) -> Result<(), MicroClawError>

Persist the exact verified experiences injected into one agent run. Re-recording the same query run replaces its selection atomically.

pub fn record_experience_rejections( &self, querying_run_id: &str, rejections: &[(String, String, f64)], ) -> Result<(), MicroClawError>

pub fn get_experience_run_detail( &self, run_id: &str, ) -> Result<Option<ExperienceRunDetail>, MicroClawError>

pub fn get_experience_summary( &self, chat_id: Option<i64>, ) -> Result<ExperienceSummary, MicroClawError>

pub fn search_verified_experiences( &self, chat_id: i64, query: &str, environment_fingerprint: Option<&str>, limit: usize, ) -> Result<Vec<VerifiedExperienceMatch>, MicroClawError>

pub fn record_verifier_result( &self, run_id: &str, verifier_type: &str, verifier_name: &str, verdict: &str, confidence: f64, evidence: Option<&str>, scope: Option<&str>, valid_until: Option<&str>, ) -> Result<(), MicroClawError>

pub fn ingest_outcome_envelope( &self, envelope: &OutcomeEnvelopeV1, ) -> Result<(), MicroClawError>

Ingest one versioned outcome envelope and atomically update its normalized projections. All outcome producers use this boundary.

pub fn get_verifier_results( &self, run_id: &str, ) -> Result<Vec<VerifierResultRecord>, MicroClawError>

pub fn get_experience_comparisons( &self, chat_id: Option<i64>, limit: usize, ) -> Result<Vec<ExperienceComparison>, MicroClawError>

impl Database

pub fn register_skill_version( &self, skill_name: &str, version: i64, content: &str, source: &str, ) -> Result<(), MicroClawError>

pub fn get_skill_lifecycle( &self, skill_name: &str, ) -> Result<Option<SkillLifecycleRecord>, MicroClawError>

pub fn get_skill_version_content( &self, skill_name: &str, version: i64, ) -> Result<Option<String>, MicroClawError>

pub fn evaluate_skill_applicability( &self, skill_name: &str, chat_id: i64, ) -> Result<SkillApplicability, MicroClawError>

Evaluate a skill against verified outcomes from the current run’s environment. Two or more matching outcomes with a pass rate below 50% form a learned contraindication until a new version is registered.

pub fn transition_skill_state( &self, skill_name: &str, to_state: &str, reason: &str, ) -> Result<bool, MicroClawError>

pub fn rollback_skill( &self, skill_name: &str, target_version: Option<i64>, reason: &str, ) -> Result<Option<(i64, String)>, MicroClawError>

pub fn get_skill_learning_summaries( &self, ) -> Result<Vec<SkillLearningSummary>, MicroClawError>

pub fn get_skill_task_utility_summaries( &self, skill_name: Option<&str>, ) -> Result<Vec<SkillTaskUtilitySummary>, MicroClawError>

pub fn get_skill_failure_patterns( &self, skill_name: Option<&str>, ) -> Result<Vec<SkillFailurePattern>, MicroClawError>

pub fn begin_skill_recovery_trial( &self, skill_name: &str, ) -> Result<bool, MicroClawError>

pub fn get_learning_claims( &self, chat_id: Option<i64>, limit: usize, ) -> Result<Vec<LearningClaim>, MicroClawError>

pub fn get_skill_candidates( &self, chat_id: Option<i64>, limit: usize, ) -> Result<Vec<SkillCandidate>, MicroClawError>

pub fn create_skill_candidate_from_claim( &self, claim_id: &str, chat_id: i64, ) -> Result<SkillCandidate, MicroClawError>

pub fn record_shadow_observation( &self, candidate_id: &str, chat_id: i64, pair_key: &str, arm: &str, run_id: &str, verdict: &str, cost_usd: f64, duration_ms: i64, evidence: Option<&str>, ) -> Result<ShadowEvaluation, MicroClawError>

pub fn get_shadow_evaluations( &self, chat_id: Option<i64>, ) -> Result<Vec<ShadowEvaluation>, MicroClawError>

pub fn promote_shadow_candidate( &self, candidate_id: &str, chat_id: i64, ) -> Result<(String, i64), MicroClawError>

pub fn archive_learning_entity( &self, entity_type: &str, entity_id: &str, chat_id: i64, ) -> Result<bool, MicroClawError>

pub fn get_learning_journal( &self, chat_id: Option<i64>, limit: usize, ) -> Result<Vec<LearningJournalEvent>, MicroClawError>

pub fn get_skill_governance_policy( &self, ) -> Result<SkillGovernancePolicy, MicroClawError>

pub fn update_skill_governance_policy( &self, policy: &SkillGovernancePolicy, ) -> Result<(), MicroClawError>

pub fn log_skill_activation( &self, skill_name: &str, chat_id: i64, ) -> Result<(), MicroClawError>

Append a row to the skill activation log. chat_id may be 0 for channel-less invocations (e.g. tests).

pub fn last_skill_activation_at( &self, skill_name: &str, ) -> Result<Option<String>, MicroClawError>

Most-recent activation timestamp for a skill, or None if never activated. Used by the auto-archive job.

pub fn skill_activation_counts_since( &self, since: &str, ) -> Result<Vec<(String, i64)>, MicroClawError>

Activation counts for every skill seen in the last since window. Returns (skill_name, count) rows ordered by count descending. Used by the insights surface and operator dashboards.

impl Database

pub fn create_learning_track( &self, chat_id: i64, name: &str, objective: &str, directions: &Value, allowed_sources: &Value, schedule: &str, timezone: &str, token_budget: i64, max_sources: i64, promotion_mode: &str, next_run: &str, ) -> Result<String, MicroClawError>

pub fn list_learning_tracks( &self, chat_id: Option<i64>, ) -> Result<Vec<LearningTrack>, MicroClawError>

pub fn learning_track_belongs_to_chat( &self, track_id: &str, chat_id: i64, ) -> Result<bool, MicroClawError>

pub fn update_learning_track_status( &self, track_id: &str, status: &str, next_run: Option<&str>, ) -> Result<bool, MicroClawError>

pub fn claim_due_learning_tracks( &self, now: &str, next_runs: &[(String, String)], ) -> Result<Vec<LearningTrack>, MicroClawError>

Atomically moves due tracks into the future before returning them. This provides at-most-once claiming per process tick; crashed epochs remain visible and the next scheduled epoch can proceed normally.

pub fn start_learning_epoch( &self, track_id: &str, experience_run_id: &str, ) -> Result<String, MicroClawError>

pub fn finish_learning_epoch( &self, epoch_id: &str, status: &str, report: Option<&str>, candidate_id: Option<&str>, error: Option<&str>, ) -> Result<(), MicroClawError>

pub fn create_learning_track_candidate( &self, epoch_id: &str, skill_name: &str, description: &str, instructions: &str, sources: &Value, tests: &Value, risk: &str, ) -> Result<String, MicroClawError>

pub fn list_learning_epochs( &self, chat_id: i64, limit: usize, ) -> Result<Vec<LearningEpoch>, MicroClawError>

pub fn list_learning_track_candidates( &self, chat_id: i64, limit: usize, ) -> Result<Vec<LearningTrackCandidate>, MicroClawError>

pub fn get_learning_track_candidate( &self, candidate_id: &str, chat_id: i64, ) -> Result<Option<LearningTrackCandidate>, MicroClawError>

pub fn update_learning_track_candidate_status( &self, candidate_id: &str, status: &str, ) -> Result<bool, MicroClawError>

pub fn start_learning_candidate_evaluation( &self, candidate_id: &str, ) -> Result<String, MicroClawError>

pub fn record_learning_candidate_trial( &self, evaluation_id: &str, test_name: &str, baseline_passed: bool, candidate_passed: bool, baseline_tokens: i64, candidate_tokens: i64, baseline_duration_ms: i64, candidate_duration_ms: i64, evidence: &Value, ) -> Result<(), MicroClawError>

pub fn finish_learning_candidate_evaluation( &self, evaluation_id: &str, passed: bool, reason: &str, ) -> Result<LearningCandidateEvaluation, MicroClawError>

pub fn list_learning_candidate_evaluations( &self, chat_id: i64, limit: usize, ) -> Result<Vec<LearningCandidateEvaluation>, MicroClawError>

pub fn list_learning_candidate_trials( &self, evaluation_id: &str, ) -> Result<Vec<LearningCandidateTrial>, MicroClawError>

impl Database

pub fn clear_chat_memory(&self, chat_id: i64) -> Result<bool, MicroClawError>

Clear memory state for a chat without deleting chat/session/message history. This removes structured memories and reflector bookkeeping for the chat.

pub fn get_reflector_cursor( &self, chat_id: i64, ) -> Result<Option<String>, MicroClawError>

pub fn set_reflector_cursor( &self, chat_id: i64, last_reflected_ts: &str, ) -> Result<(), MicroClawError>

pub fn insert_memory( &self, chat_id: Option<i64>, content: &str, category: &str, ) -> Result<i64, MicroClawError>

pub fn insert_memory_with_metadata( &self, chat_id: Option<i64>, content: &str, category: &str, source: &str, confidence: f64, ) -> Result<i64, MicroClawError>

pub fn get_memories_for_context( &self, chat_id: i64, limit: usize, ) -> Result<Vec<Memory>, MicroClawError>

pub fn get_all_memories_for_chat( &self, chat_id: Option<i64>, ) -> Result<Vec<Memory>, MicroClawError>

pub fn search_memories( &self, chat_id: i64, query: &str, limit: usize, ) -> Result<Vec<Memory>, MicroClawError>

Keyword search in memories visible to chat_id (own + global).

pub fn search_memories_with_options( &self, chat_id: i64, query: &str, limit: usize, include_archived: bool, broad_recall: bool, ) -> Result<Vec<Memory>, MicroClawError>

pub fn delete_memory(&self, id: i64) -> Result<bool, MicroClawError>

Delete a memory row by id. Returns true if a row was deleted.

pub fn set_memory_expires_at( &self, id: i64, expires_at: Option<&str>, ) -> Result<bool, MicroClawError>

Set or clear the expires_at of a memory. Pass None to clear.

pub fn prune_expired_memories(&self, now: &str) -> Result<usize, MicroClawError>

Hard-delete memories whose expires_at is at or before now. Returns the number of rows deleted. Called from the reflector on its scheduled tick.

pub fn update_memory_content( &self, id: i64, content: &str, category: &str, ) -> Result<bool, MicroClawError>

Update content and category of an existing memory. Returns true if found.

pub fn update_memory_with_metadata( &self, id: i64, content: &str, category: &str, confidence: f64, source: &str, ) -> Result<bool, MicroClawError>

pub fn update_memory_embedding_model( &self, id: i64, model: &str, ) -> Result<bool, MicroClawError>

pub fn get_memories_without_embedding( &self, chat_id: Option<i64>, limit: usize, ) -> Result<Vec<Memory>, MicroClawError>

pub fn get_all_active_memories( &self, ) -> Result<Vec<(i64, String)>, MicroClawError>

pub fn get_memory_by_id( &self, id: i64, ) -> Result<Option<Memory>, MicroClawError>

Get a single memory by id.

pub fn touch_memory_last_seen( &self, id: i64, confidence_floor: Option<f64>, ) -> Result<bool, MicroClawError>

pub fn archive_memory(&self, id: i64) -> Result<bool, MicroClawError>

pub fn archive_stale_memories( &self, stale_days: i64, ) -> Result<usize, MicroClawError>

pub fn archive_excess_memories( &self, chat_id: Option<i64>, max_entries: usize, ) -> Result<usize, MicroClawError>

Archive the lowest-confidence, least-recently-seen memories for a chat (or global if chat_id is None) when the count exceeds max_entries. Returns the number of memories archived.

pub fn supersede_memory( &self, from_memory_id: i64, new_content: &str, category: &str, source: &str, confidence: f64, reason: Option<&str>, ) -> Result<i64, MicroClawError>

pub fn kg_insert_triple( &self, subject: &str, predicate: &str, object: &str, chat_id: Option<i64>, valid_from: &str, confidence: f64, source: &str, source_memory_id: Option<i64>, ) -> Result<i64, MicroClawError>

Insert a new knowledge graph triple.

pub fn kg_invalidate_triple( &self, id: i64, valid_to: &str, ) -> Result<bool, MicroClawError>

Invalidate a triple by setting its valid_to timestamp.

pub fn kg_query_subject( &self, subject: &str, chat_id: Option<i64>, as_of: Option<&str>, ) -> Result<Vec<KgTriple>, MicroClawError>

Query triples by subject, optionally filtered by a point-in-time (as_of).

pub fn kg_query_object( &self, object: &str, chat_id: Option<i64>, ) -> Result<Vec<KgTriple>, MicroClawError>

Query triples by object (reverse lookup).

pub fn kg_distinct_entities( &self, chat_id: Option<i64>, limit: usize, ) -> Result<Vec<String>, MicroClawError>

Distinct active entities (subjects and objects) for a chat, used to find which graph nodes a query mentions so retrieval can be seeded from them.

pub fn kg_neighborhood( &self, chat_id: Option<i64>, seeds: &[String], max_hops: usize, total_limit: usize, ) -> Result<Vec<KgTriple>, MicroClawError>

Bounded breadth-first expansion of the knowledge graph from seed entities, returning the active triples reachable within max_hops. This is the graph-augmented retrieval primitive: seed from entities a query mentions, then pull in directly-connected facts (and their neighbours) so multi-hop context surfaces without the agent having to query the graph by hand. Bounded by total_limit triples and a per-hop frontier cap, so it stays cheap even on large graphs.

pub fn kg_timeline( &self, subject: &str, chat_id: Option<i64>, ) -> Result<Vec<KgTriple>, MicroClawError>

Get a timeline of all triples for a subject, including invalidated ones.

pub fn kg_stats( &self, chat_id: Option<i64>, ) -> Result<(usize, usize, usize), MicroClawError>

Get knowledge graph stats (total triples, active, invalidated).

pub fn kg_prune_excess( &self, chat_id: i64, max_triples: usize, ) -> Result<usize, MicroClawError>

Delete oldest invalidated triples when count exceeds max_triples for a chat. If still over limit after pruning invalidated, also deletes oldest active triples by confidence.

pub fn log_reflector_run( &self, chat_id: i64, started_at: &str, finished_at: &str, extracted_count: usize, inserted_count: usize, updated_count: usize, skipped_count: usize, dedup_method: &str, parse_ok: bool, error_text: Option<&str>, ) -> Result<i64, MicroClawError>

pub fn log_memory_injection( &self, chat_id: i64, retrieval_method: &str, candidate_count: usize, selected_count: usize, omitted_count: usize, tokens_est: usize, ) -> Result<i64, MicroClawError>

pub fn get_memory_observability_summary( &self, chat_id: Option<i64>, ) -> Result<MemoryObservabilitySummary, MicroClawError>

pub fn get_memory_reflector_runs( &self, chat_id: Option<i64>, since: Option<&str>, limit: usize, offset: usize, ) -> Result<Vec<MemoryReflectorRun>, MicroClawError>

pub fn get_memory_injection_logs( &self, chat_id: Option<i64>, since: Option<&str>, limit: usize, offset: usize, ) -> Result<Vec<MemoryInjectionLog>, MicroClawError>

impl Database

pub fn upsert_metrics_history( &self, point: &MetricsHistoryPoint, ) -> Result<(), MicroClawError>

pub fn get_metrics_history( &self, since_ts_ms: i64, limit: usize, ) -> Result<Vec<MetricsHistoryPoint>, MicroClawError>

pub fn cleanup_metrics_history_before( &self, before_ts_ms: i64, ) -> Result<usize, MicroClawError>

pub fn get_runtime_meta( &self, key: &str, ) -> Result<Option<String>, MicroClawError>

Read a runtime key from the db_meta KV table (also used for schema_version/embedding_dim). Namespaced keys recommended.

pub fn set_runtime_meta( &self, key: &str, value: &str, ) -> Result<(), MicroClawError>

Upsert a runtime key in the db_meta KV table.

pub fn list_runtime_meta_prefix( &self, prefix: &str, ) -> Result<Vec<(String, String)>, MicroClawError>

List runtime keys sharing a prefix (sorted by key).

pub fn delete_runtime_meta(&self, key: &str) -> Result<bool, MicroClawError>

Delete a single runtime key; returns whether a row was removed.

pub fn delete_runtime_meta_prefix( &self, prefix: &str, ) -> Result<usize, MicroClawError>

Delete every runtime key sharing a prefix; returns removed count.

pub fn contract_verdict_counts_since( &self, since: &str, ) -> Result<(i64, i64), MicroClawError>

Completion-contract verdict tallies (verified, failed) recorded at or after since (RFC 3339). Verdicts are the contract events written when a sub-agent run’s exit criteria are checked.

impl Database

pub fn enqueue_outbox_message( &self, chat_id: i64, channel: &str, payload_text: &str, ) -> Result<i64, MicroClawError>

Queue a final reply whose direct channel delivery failed. The outbox flush loop retries it with backoff until delivered or terminally failed.

pub fn create_outbound_delivery( &self, delivery_id: &str, chat_id: i64, channel: &str, full_payload_text: &str, chunks: &[String], ) -> Result<Vec<i64>, MicroClawError>

Persist a complete outbound message and its independently retryable chunks before the first network call.

pub fn list_due_outbox_messages( &self, now_iso: &str, limit: usize, ) -> Result<Vec<OutboxMessageRecord>, MicroClawError>

pub fn mark_outbox_delivered(&self, id: i64) -> Result<(), MicroClawError>

pub fn mark_outbox_sending(&self, id: i64) -> Result<bool, MicroClawError>

pub fn mark_outbox_retry( &self, id: i64, attempts: i64, next_attempt_at: Option<&str>, last_error: &str, terminal_fail: bool, ) -> Result<(), MicroClawError>

pub fn recover_sending_outbox_messages(&self) -> Result<usize, MicroClawError>

Reset chunks left in sending by an unclean shutdown. Stable channel idempotency keys make replay safe on supporting transports (Weixin).

pub fn outbound_delivery_is_complete( &self, delivery_id: &str, ) -> Result<bool, MicroClawError>

pub fn finalize_outbound_delivery( &self, delivery_id: &str, sender_name: &str, ) -> Result<bool, MicroClawError>

Store the full logical message once, after every external chunk is delivered. Returns true only for the caller that performed the insert.

pub fn count_outbox_pending(&self) -> Result<i64, MicroClawError>

Pending + retry outbox depth (governance/observability).

pub fn outbound_delivery_health( &self, ) -> Result<OutboundDeliveryHealth, MicroClawError>

Read-only delivery health snapshot for diagnostics and monitoring.

impl Database

pub fn create_paired_device( &self, device_id: &str, label: &str, platform: Option<&str>, token_hash: &str, prefix: &str, ) -> Result<i64, MicroClawError>

pub fn list_paired_devices( &self, ) -> Result<Vec<PairedDeviceRecord>, MicroClawError>

pub fn get_paired_device_by_device_id( &self, device_id: &str, ) -> Result<Option<PairedDeviceRecord>, MicroClawError>

pub fn revoke_paired_device(&self, id: i64) -> Result<bool, MicroClawError>

Soft-revoke a device. Returns false when no such row exists.

pub fn validate_paired_device_token_hash( &self, token_hash: &str, ) -> Result<Option<PairedDeviceRecord>, MicroClawError>

Resolve a presented token hash to an active device, bumping last_seen_at. Revoked devices resolve to None.

impl Database

pub fn save_session( &self, chat_id: i64, messages_json: &str, ) -> Result<(), MicroClawError>

pub fn save_session_with_meta( &self, chat_id: i64, messages_json: &str, parent_session_key: Option<&str>, fork_point: Option<i64>, skill_envs_json: Option<&str>, ) -> Result<(), MicroClawError>

pub fn load_session( &self, chat_id: i64, ) -> Result<Option<(String, String)>, MicroClawError>

pub fn set_session_label( &self, chat_id: i64, label: &str, ) -> Result<(), MicroClawError>

Overwrite the session label for a chat. No-op if the chat has no session row yet. Used by the title generator background task.

pub fn get_session_label_and_length( &self, chat_id: i64, ) -> Result<Option<(Option<String>, usize)>, MicroClawError>

Return the current session label + message count for a chat. Used to decide whether the title generator should run.

pub fn save_session_settings( &self, chat_id: i64, settings: &SessionSettings, ) -> Result<(), MicroClawError>

pub fn load_session_settings( &self, chat_id: i64, ) -> Result<Option<SessionSettings>, MicroClawError>

pub fn load_session_meta( &self, chat_id: i64, ) -> Result<Option<SessionMetaRow>, MicroClawError>

pub fn list_session_meta( &self, limit: usize, ) -> Result<Vec<SessionTreeRow>, MicroClawError>

pub fn delete_session(&self, chat_id: i64) -> Result<bool, MicroClawError>

impl Database

pub fn save_session_skill_envs( &self, chat_id: i64, skill_envs_json: &str, ) -> Result<(), MicroClawError>

pub fn load_session_skill_envs( &self, chat_id: i64, ) -> Result<Option<String>, MicroClawError>

impl Database

pub fn create_subagent_run( &self, params: CreateSubagentRunParams<'_>, ) -> Result<(), MicroClawError>

pub fn record_subagent_progress( &self, run_id: &str, progress_text: &str, ) -> Result<Option<String>, MicroClawError>

Record a progress snapshot for a running sub-agent: update the latest progress text/time on the run and append a progress event to its timeline. Returns the previous last_progress_at (for throttling).

pub fn mark_subagent_queued(&self, run_id: &str) -> Result<(), MicroClawError>

pub fn mark_subagent_running(&self, run_id: &str) -> Result<(), MicroClawError>

pub fn mark_subagent_finished( &self, params: FinishSubagentRunParams<'_>, ) -> Result<(), MicroClawError>

pub fn recover_orphaned_subagent_runs(&self) -> Result<usize, MicroClawError>

Startup crash recovery: sub-agent runs execute in-process, so any run still marked in-flight when a new process boots was killed mid-run. Retire them as interrupted so lists and gates stop counting them, and return how many rows were fixed.

pub fn request_subagent_cancel( &self, run_id: &str, chat_id: i64, ) -> Result<bool, MicroClawError>

pub fn list_subagent_runs( &self, chat_id: i64, limit: usize, ) -> Result<Vec<SubagentRunRecord>, MicroClawError>

pub fn avg_completed_subagent_duration_secs( &self, chat_id: i64, ) -> Result<Option<i64>, MicroClawError>

Average wall-clock duration (seconds) of recently-completed sub-agent runs in a chat, for rough ETA hints. None when there’s no completed history.

pub fn list_active_subagent_runs( &self, ) -> Result<Vec<SubagentRunRecord>, MicroClawError>

All currently-active sub-agent runs across chats (accepted/queued/running), oldest first. Used by the proactive task-standup loop.

pub fn get_subagent_run( &self, run_id: &str, chat_id: i64, ) -> Result<Option<SubagentRunRecord>, MicroClawError>

pub fn list_subagent_children( &self, parent_run_id: &str, ) -> Result<Vec<SubagentRunRecord>, MicroClawError>

All child runs of a parent run, oldest first.

pub fn resolve_subagent_run_id( &self, chat_id: i64, run_id_or_label: &str, ) -> Result<Option<String>, MicroClawError>

Resolve a sub-agent reference that is either an exact run_id or a human-friendly label, scoped to a chat. Exact run_id wins; otherwise the most recent run with that label is returned, preferring active ones.

pub fn is_subagent_cancel_requested( &self, run_id: &str, ) -> Result<bool, MicroClawError>

pub fn count_active_subagent_runs_for_chat( &self, chat_id: i64, ) -> Result<i64, MicroClawError>

pub fn count_active_subagent_children( &self, parent_run_id: &str, ) -> Result<i64, MicroClawError>

pub fn enqueue_subagent_announce( &self, run_id: &str, chat_id: i64, caller_channel: &str, payload_text: &str, ) -> Result<(), MicroClawError>

pub fn list_due_subagent_announces( &self, now_iso: &str, limit: usize, ) -> Result<Vec<SubagentAnnounceRecord>, MicroClawError>

pub fn mark_subagent_announce_sent(&self, id: i64) -> Result<(), MicroClawError>

pub fn mark_subagent_announce_retry( &self, id: i64, attempts: i64, next_attempt_at: Option<&str>, last_error: &str, terminal_fail: bool, ) -> Result<(), MicroClawError>

pub fn append_subagent_event( &self, run_id: &str, event_type: &str, detail: Option<&str>, ) -> Result<(), MicroClawError>

pub fn list_subagent_events( &self, run_id: &str, limit: usize, ) -> Result<Vec<SubagentEventRecord>, MicroClawError>

pub fn set_subagent_focus( &self, chat_id: i64, run_id: &str, ) -> Result<(), MicroClawError>

pub fn clear_subagent_focus(&self, chat_id: i64) -> Result<(), MicroClawError>

pub fn get_subagent_focus( &self, chat_id: i64, ) -> Result<Option<String>, MicroClawError>

pub fn get_subagent_observability_snapshot( &self, chat_id: Option<i64>, recent_limit: usize, ) -> Result<SubagentObservabilitySnapshot, MicroClawError>

impl Database

pub fn create_scheduled_task( &self, chat_id: i64, prompt: &str, schedule_type: &str, schedule_value: &str, next_run: &str, ) -> Result<i64, MicroClawError>

pub fn create_scheduled_task_with_timezone( &self, chat_id: i64, prompt: &str, schedule_type: &str, schedule_value: &str, timezone: &str, next_run: &str, ) -> Result<i64, MicroClawError>

pub fn create_scheduled_task_full( &self, chat_id: i64, prompt: &str, schedule_type: &str, schedule_value: &str, timezone: &str, next_run: &str, exit_criteria: Option<&str>, ) -> Result<i64, MicroClawError>

pub fn create_scheduled_task_lifecycle( &self, chat_id: i64, prompt: &str, schedule_type: &str, schedule_value: &str, timezone: &str, next_run: &str, exit_criteria: Option<&str>, max_runs: Option<i64>, not_after: Option<&str>, ) -> Result<i64, MicroClawError>

pub fn get_due_tasks( &self, now: &str, ) -> Result<Vec<ScheduledTask>, MicroClawError>

pub fn get_tasks_for_chat( &self, chat_id: i64, ) -> Result<Vec<ScheduledTask>, MicroClawError>

pub fn list_scheduled_tasks( &self, status: Option<&str>, limit: usize, ) -> Result<Vec<ScheduledTask>, MicroClawError>

List scheduled tasks across all chats for management views. status filters to one status; None returns every task. Newest first.

pub fn get_task_by_id( &self, task_id: i64, ) -> Result<Option<ScheduledTask>, MicroClawError>

pub fn get_scheduled_task( &self, task_id: i64, ) -> Result<Option<ScheduledTask>, MicroClawError>

Fetch one scheduled task by id regardless of status (management/ detail views and tests need retired tasks too).

pub fn update_task_status( &self, task_id: i64, status: &str, ) -> Result<bool, MicroClawError>

pub fn requeue_scheduled_task( &self, task_id: i64, next_run: &str, ) -> Result<bool, MicroClawError>

pub fn update_task_after_run( &self, task_id: i64, last_run: &str, next_run: Option<&str>, success: bool, ) -> Result<(), MicroClawError>

pub fn update_task_after_run_lifecycle( &self, task_id: i64, last_run: &str, next_run: Option<&str>, success: bool, lifecycle_finished: bool, ) -> Result<(), MicroClawError>

lifecycle_finished marks a RECURRING task that just retired on purpose (max_runs reached / not_after passed): it becomes completed regardless of this run’s outcome, so DLQ auto-replay never resurrects a task whose lifecycle has ended. run_count increments on every run.

pub fn recover_running_tasks(&self) -> Result<usize, MicroClawError>

pub fn log_task_run( &self, task_id: i64, chat_id: i64, started_at: &str, finished_at: &str, duration_ms: i64, success: bool, result_summary: Option<&str>, ) -> Result<i64, MicroClawError>

pub fn get_task_run_logs( &self, task_id: i64, limit: usize, ) -> Result<Vec<TaskRunLog>, MicroClawError>

pub fn get_task_run_summary_since( &self, since: Option<&str>, ) -> Result<(i64, i64), MicroClawError>

pub fn insert_scheduled_task_dlq( &self, task_id: i64, chat_id: i64, started_at: &str, finished_at: &str, duration_ms: i64, error_summary: Option<&str>, ) -> Result<i64, MicroClawError>

pub fn list_scheduled_task_dlq( &self, chat_id: Option<i64>, task_id: Option<i64>, include_replayed: bool, limit: usize, ) -> Result<Vec<ScheduledTaskDlqEntry>, MicroClawError>

pub fn mark_scheduled_task_dlq_replayed( &self, dlq_id: i64, note: Option<&str>, ) -> Result<bool, MicroClawError>

pub fn delete_task(&self, task_id: i64) -> Result<bool, MicroClawError>

pub fn count_scheduled_task_dlq( &self, include_replayed: bool, ) -> Result<i64, MicroClawError>

Exact depth of the scheduled-task dead-letter queue (unlike list_scheduled_task_dlq, this is not clamped by a LIMIT).

impl Database

pub fn claim_due_tasks( &self, now: &str, limit: usize, ) -> Result<Vec<ScheduledTask>, MicroClawError>

impl Database

pub fn get_cached_tool_result( &self, cache_key: &str, now: &str, ) -> Result<Option<CachedToolResult>, MicroClawError>

Look up a cached tool result by key; returns None if missing or past its TTL. Passing now as an RFC3339 string lets callers control “now” deterministically in tests.

pub fn put_cached_tool_result( &self, cache_key: &str, tool_name: &str, content: &str, is_error: bool, metadata_json: Option<&str>, expires_at: &str, ) -> Result<(), MicroClawError>

Insert or replace a cached tool result. Only non-error results should be cached in practice; the is_error flag is exposed so callers can choose a policy.

pub fn prune_tool_result_cache( &self, now: &str, ) -> Result<usize, MicroClawError>

Delete all expired cache rows. Returns number of rows deleted.

pub fn save_tool_artifact( &self, artifact_id: &str, chat_id: i64, tool_name: &str, content: &str, expires_at: &str, ) -> Result<(), MicroClawError>

Persist a tool-result artifact (full content) so the agent can fetch slices later via fetch_artifact. The caller is responsible for generating a unique artifact_id.

pub fn get_tool_artifact_slice( &self, artifact_id: &str, offset: usize, length: usize, now: &str, ) -> Result<Option<(ToolArtifactMeta, String)>, MicroClawError>

Fetch a character-range slice of a stored artifact. Returns (meta, slice, returned_chars) if the artifact exists and is not expired. offset and length are interpreted as Unicode code points to keep the cap predictable across multi-byte content.

pub fn prune_tool_artifacts(&self, now: &str) -> Result<usize, MicroClawError>

Delete expired artifact rows. Returns number of rows deleted.

impl Database

pub fn mark_turn_active( &self, chat_id: i64, channel: &str, ) -> Result<(), MicroClawError>

Record that an interactive turn is in flight for chat_id. One row per chat: a re-entrant start (queued follow-up in the same chat) just refreshes the timestamp.

pub fn mark_turn_active_with_context( &self, chat_id: i64, channel: &str, chat_type: &str, run_id: Option<&str>, ) -> Result<(), MicroClawError>

Record an interactive run together with the routing context needed to resume it after process restart.

pub fn mark_turn_recovery_started( &self, chat_id: i64, run_id: &str, ) -> Result<(), MicroClawError>

Attach a new process-local run id to an interrupted turn without overwriting its last safe checkpoint. If recovery crashes before the next checkpoint, the following startup can resume from the same state.

pub fn update_turn_progress( &self, chat_id: i64, progress: &str, ) -> Result<(), MicroClawError>

Update the rolling progress snapshot for an in-flight interactive turn. No-op for chats without an active turn (e.g. scheduler-driven runs).

pub fn checkpoint_active_turn( &self, chat_id: i64, phase: &str, iteration: i64, session_json: Option<&str>, resumable: bool, progress_text: Option<&str>, tool_summary: Option<&str>, ) -> Result<(), MicroClawError>

Persist a durable agent-loop boundary.

session_json must end at a provider-neutral message boundary. Callers set resumable=false while a side-effecting tool may be in flight, so startup recovery can never blindly replay an operation with uncertain outcome.

pub fn list_active_turns(&self) -> Result<Vec<InterruptedTurn>, MicroClawError>

Inspect in-flight interactive runs without mutating recovery state.

pub fn clear_turn_active(&self, chat_id: i64) -> Result<(), MicroClawError>

The interactive turn for chat_id finished (any outcome).

pub fn take_interrupted_turns( &self, ) -> Result<Vec<InterruptedTurn>, MicroClawError>

Startup crash recovery: return-and-clear every turn that was in flight when the previous process died. The table is emptied in the same transaction so a second caller can never double-notify.

impl Database

pub fn log_llm_usage( &self, chat_id: i64, caller_channel: &str, provider: &str, model: &str, input_tokens: i64, output_tokens: i64, request_kind: &str, ) -> Result<i64, MicroClawError>

pub fn get_llm_usage_summary( &self, chat_id: Option<i64>, ) -> Result<LlmUsageSummary, MicroClawError>

pub fn get_llm_usage_summary_since( &self, chat_id: Option<i64>, since: Option<&str>, ) -> Result<LlmUsageSummary, MicroClawError>

pub fn get_llm_usage_by_model( &self, chat_id: Option<i64>, since: Option<&str>, limit: Option<usize>, ) -> Result<Vec<LlmModelUsageSummary>, MicroClawError>

impl Database

pub fn new(data_dir: &str) -> Result<Self, MicroClawError>