Struct Storage 

pub struct Storage {
    pub db_path: PathBuf,
    pub content_dim: usize,
    pub trigger_dim: usize,
    /* private fields */
}

Fields

db_path: PathBuf

content_dim: usize

trigger_dim: usize

Implementations

impl Storage

pub fn insert_chunk(&self, c: &ChunkRow) -> Result<()>

pub fn insert_vec_content(&self, chunk_id: &str, emb: &[u8]) -> Result<()>

pub fn insert_vec_trigger(&self, chunk_id: &str, emb: &[u8]) -> Result<()>

pub fn list_chunks( &self, state: Option<&str>, origin: Option<&str>, limit: usize, offset: usize, ) -> Result<Vec<Value>>

Paginated chunk listing for the web viewer. Filters by exact state and origin when provided; returns a compact projection (content truncated to a preview) ordered newest-first. Read-only — never mutates.

pub fn get_chunk(&self, id: &str) -> Result<Option<Value>>

pub fn update_chunk_state( &self, id: &str, state: &str, reason: Option<&str>, now: &str, ) -> Result<()>

pub fn update_chunk_confidence( &self, id: &str, conf: f64, reason: Option<&str>, now: &str, ) -> Result<()>

pub fn update_chunk_last_used(&self, id: &str, now: &str) -> Result<()>

pub fn get_chunk_by_hash(&self, hash: &str) -> Result<Option<Value>>

pub fn search_vec_content( &self, query: &[f32], limit: usize, ) -> Result<Vec<(String, f32)>>

pub fn search_vec_trigger( &self, query: &[f32], limit: usize, ) -> Result<Vec<(String, f32)>>

pub fn search_lexical( &self, query: &str, limit: usize, ) -> Result<Vec<(String, f32)>>

Lexical/BM25 retrieval channel (hybrid 检索的词法一路). Builds a safe FTS5 MATCH from the query’s alphanumeric tokens and returns up to limit non-archived, non-spark chunks ranked by BM25, with each score normalised to (0,1] (best match → 1.0) so it can fuse alongside cosine sims. Returns empty when the query has no usable tokens (degrades to vector-only).

pub fn get_chunks_by_ids(&self, ids: &[&str]) -> Result<HashMap<String, Value>>

Fetch multiple chunks by id in one query; returns a map of id → chunk JSON.

pub fn is_hash_invalidated(&self, hash: &str) -> Result<bool>

pub fn insert_invalidated_hash( &self, hash: &str, reason: Option<&str>, ts: &str, ) -> Result<()>

pub fn get_deps(&self, chunk_id: &str) -> Result<Vec<DepEdge>>

pub fn get_deps_batch( &self, srcs: &[&str], ) -> Result<HashMap<String, Vec<DepEdge>>>

Batch variant of get_deps: fetch outgoing edges for many sources in one query. Returns src → [(dst, kind, dst_lib)]. Sources with no edges are simply absent from the map.

pub fn get_reverse_deps(&self, chunk_id: &str) -> Result<Vec<String>>

pub fn insert_dep( &self, src: &str, dst: &str, kind: &str, dst_lib: Option<&str>, ) -> Result<()>

pub fn upsert_chunk_success_trace( &self, chunk_id: &str, trace_id: &str, ts: &str, ) -> Result<()>

impl Storage

pub fn upsert_governance_proposal( &self, id: &str, chunk_id: &str, proposal_type: &str, reason: &str, evidence_count: i64, evidence_score: f64, actor_count: i64, now: &str, ) -> Result<()>

pub fn list_governance_proposals( &self, state: &str, limit: usize, ) -> Result<Vec<Value>>

Read-only listing of governance proposals for the web review queue, joined with a compact chunk projection so a reviewer sees what was flagged and why (evidence_score / actor_count) in one round-trip. Ordered by evidence_score DESC so the strongest cases surface first.

pub fn request_evolve(&self, id: &str, reason: &str, now: &str) -> Result<()>

pub fn request_evolve_at( &self, id: &str, reason: &str, now: &str, next_retry_at: Option<&str>, ) -> Result<()>

pub fn claim_evolve_request_with_reason( &self, now: &str, stale_before: &str, ) -> Result<Option<EvolveRequestClaim>>

pub fn defer_evolve_request( &self, id: &str, note: &str, next_retry_at: &str, ) -> Result<()>

pub fn finish_evolve_request( &self, id: &str, state: &str, note: Option<&str>, now: &str, ) -> Result<()>

pub fn finish_covered_evolve_requests( &self, requested_before: &str, now: &str, ) -> Result<()>

pub fn update_episodic_log_state_by_id( &self, id: &str, state: &str, note: Option<&str>, outcome: Option<&str>, ) -> Result<()>

Update by primary-key id (used after distill where we have the row id, not trace_id).

pub fn finish_distill_log( &self, id: &str, state: &str, note: Option<&str>, prompt_tokens: i64, completion_tokens: i64, accounted_at: &str, ) -> Result<()>

pub fn claim_distill_batch( &self, run_id: &str, limit: usize, locked_at: &str, ) -> Result<Vec<Value>>

Claim a batch of ‘new’ logs for distillation: mark them ‘screening’ atomically. Returns the claimed rows (with distill_run_id set to run_id).

pub fn query_episodic_logs_open(&self, limit: usize) -> Result<Vec<Value>>

impl Storage

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

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

pub fn get_meta_or(&self, key: &str, default: &str) -> String

impl Storage

pub fn attach_shared(&self, path: &str, alias: &str) -> Result<()>

pub fn lib_id(&self) -> Result<String>

pub fn db_size_bytes(&self) -> Result<i64>

On-disk size of the main database file in bytes (page_count * page_size).

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

Reclaim space freed by curate’s log compaction and trace purges: checkpoint and truncate the WAL, then VACUUM to return free pages to the OS. Returns (before_bytes, after_bytes). Must run outside any transaction.

impl Storage

pub fn insert_usage_trace( &self, trace_id: &str, chunk_id: Option<&str>, event: &str, strength: f64, similarity: Option<f64>, refine_mode: Option<&str>, tokens: Option<i64>, rank: Option<i64>, attribution: Option<&str>, source: &str, ts: &str, ) -> Result<usize>

pub fn replace_used_trace( &self, trace_id: &str, used_ids: &[String], strength: f64, attribution: &str, source: &str, ts: &str, ) -> Result<()>

pub fn merge_used_trace( &self, trace_id: &str, used_ids: &[String], strength: f64, attribution: &str, source: &str, ts: &str, ) -> Result<()>

pub fn refresh_chunk_last_used(&self, chunk_id: &str, now: &str) -> Result<()>

pub fn get_outcome_for_trace(&self, trace_id: &str) -> Result<Option<String>>

pub fn purge_usage_trace(&self, before_ts: &str) -> Result<usize>

pub fn upsert_episodic_log(&self, log: &EpisodicLogRow) -> Result<()>

pub fn get_episodic_log(&self, trace_id: &str) -> Result<Option<Value>>

pub fn update_episodic_log_state( &self, trace_id: &str, state: &str, note: Option<&str>, outcome: Option<&str>, ) -> Result<()>

pub fn patch_episodic_log_content( &self, trace_id: &str, query: Option<&str>, output: Option<&str>, output_summary: Option<&str>, nomination: Option<&str>, priority: i64, ) -> Result<()>

Patch content fields on an existing episodic_log row (補写: output_summary, nomination, etc.)

pub fn update_trace_lifecycle( &self, trace_id: &str, task_state: &str, completed_at: Option<&str>, usage_state: Option<&str>, used_ids: Option<&str>, used_attribution: Option<&str>, used_complete: Option<bool>, ) -> Result<()>

pub fn upsert_confidence_evidence( &self, id: &str, trace_id: Option<&str>, chunk_id: &str, kind: &str, target: f64, alpha: f64, reason: &str, context_key: Option<&str>, ts: &str, provenance: &str, ) -> Result<()>

pub fn observed_outcome_count(&self, chunk_id: &str) -> Result<i64>

方案 C / 门3:某 chunk 实际观测到的结果数(只数 provenance=‘observed’ 的 outcome 证据)。供 appraise 门3「证据充分性」判断邻居是否有观测历史。

pub fn context_stat_present_batch( &self, chunk_ids: &[&str], context_key: &str, ) -> Result<HashSet<String>>

方案 F 门2:返回在给定 context_key(coarse signature 桶)下有校准历史的 chunk 集合。rich 嵌入说「近」的邻居里,有多少在 signature 通道也「近」(有该 情境类的观测),低 = rich 嵌入在撒谎(疑似假共振)。

pub fn insert_verdict_log( &self, verdict_id: &str, trace_id: &str, situation_sig: &str, emitted_valence: Option<&str>, emitted_conf: Option<f64>, emitted_strength: f64, emitted_tier: Option<&str>, abstain_reason: Option<&str>, emitted_at: &str, ) -> Result<()>

方案 B:写一条 verdict_log(emit 时)。表态填 valence/conf/strength/tier, 弃权填 abstain_reason(其余 NULL)。outcome 列留空,等 record 回填。

pub fn backfill_verdict_outcome( &self, trace_id: &str, observed_outcome: f64, provenance: &str, observed_at: &str, ) -> Result<()>

方案 B/H:用 record 的实际结果回填 verdict_log。provenance 区分 ‘observed’(真实采取动作并观测到结果,计入校准)与 ‘counterfactual_censored’(因警告回避了动作,不计入校准,见原则 3)。

pub fn load_calibration_map(&self) -> Result<Vec<(f64, f64, f64)>>

方案 E:加载校准映射(分桶查表)。返回 (claimed_lo, claimed_hi, observed_rate)。

pub fn verdict_calibration_samples(&self) -> Result<Vec<(f64, f64, f64)>>

方案 E/B:取所有「observed」回填的 (emitted_strength, emitted_conf, hit) 三元组, 供 curate 重算校准映射(按 strength 分桶,因为 emit 时 calibrate_confidence 正是用原始 strength 查表)与 inspect 算 ECE(按 conf 分桶,衡量声称置信度的 真实兑现率)。两者域不同,故同时返回,调用方各取所需。

hit = verdict 的关切是否兑现,只对方向性 verdict 有良定义: affirm → 命中=结果 ok(observed_outcome<0);caution → 命中=结果 fail。 neutral(无信号)与 mixed(方向歧义)不参与校准 —— 否则把「没表态」误记成 「预测失败」,污染校准映射与 ECE。

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

方案 B:verdict_log 概览 (total, abstained, with_observed_outcome)。供 inspect 仪表盘。

pub fn replace_calibration_map( &self, buckets: &[(f64, f64, f64, i64)], now: &str, ) -> Result<()>

方案 E:重写 calibration_map(curate 调用)。buckets = (lo, hi, rate, n)。

pub fn delete_trace_confidence_evidence( &self, trace_id: &str, kinds: &[&str], ) -> Result<()>

pub fn delete_chunk_trace_confidence_evidence( &self, trace_id: &str, chunk_id: &str, kind: &str, ) -> Result<()>

pub fn confidence_evidence_for_chunk( &self, chunk_id: &str, ) -> Result<Vec<Value>>

pub fn insert_feedback_event( &self, id: &str, trace_id: &str, chunk_id: &str, signal: &str, strength: f64, source: &str, actor: Option<&str>, reason: Option<&str>, context_key: Option<&str>, ts: &str, ) -> Result<usize>

pub fn delete_feedback_event( &self, trace_id: &str, chunk_id: &str, signal: &str, ) -> Result<usize>

pub fn update_chunk_last_decayed_at(&self, id: &str, now: &str) -> Result<()>

pub fn update_context_stat( &self, chunk_id: &str, context_key: &str, success: i64, failure: i64, positive: i64, negative: i64, now: &str, ) -> Result<()>

pub fn context_score( &self, chunk_id: &str, context_key: &str, prior_m: f64, base_rate: f64, ) -> Result<f64>

pub fn context_scores_batch( &self, chunk_ids: &[&str], context_key: &str, prior_m: f64, base_rate: f64, ) -> Result<HashMap<String, f64>>

Batch variant of context_score: one query for many chunk ids under a single context key. Chunks with no stats are absent from the map (score 0).

impl Storage

pub fn open( db_path: impl AsRef<Path>, content_dim: usize, trigger_dim: usize, ) -> Result<Self>

pub fn open_readonly(db_path: impl AsRef<Path>) -> Result<Self>

pub fn begin_immediate(&self) -> Result<()>

pub fn commit(&self) -> Result<()>

pub fn rollback(&self) -> Result<()>