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 replace_chunk_entities( &self, chunk_id: &str, entities: &[ExtractedEntity], ) -> Result<()>

Replace a chunk’s associative entities (idempotent: clear then insert).

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

Entities of the given chunks (for seeding 2-hop spreading from the highest base-relevance candidates). Returns id → its entity strings.

pub fn entity_links(&self, entities: &[&str]) -> Result<Vec<(String, String)>>

Reverse index: chunks linked to any of the given entities, restricted to recall-valid chunks (mirrors search_lexical: not archived, not spark). Returns (entity, chunk_id) pairs; the caller computes fan = group size and the ACT-R 1/fan normalization in pure logic (IO/logic separation).

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 export_chunks(&self, include_archived: bool) -> Result<Vec<Value>>

R9 — export full chunk records (not previews) as portable rows for innate export. Sparks are excluded (recall-exempt). Archived chunks are skipped unless include_archived. Returns the fields needed to re-add the chunk elsewhere plus provenance for auditing.

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<()>

After a successful generic distill+curate run, bulk-complete the OTHER pending requests queued before this run started — they are genuinely subsumed by it (distill_batch drains every eligible episodic log; curate runs globally).

governance / governance_ready requests are deliberately excluded: they carry per-request semantics and are special-cased on every other path (claim priority, curate_only completion in the skip branches), so a generic distill run must not silently mark them done across the reason boundary. They stay pending and are serviced on their own claim turn.

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 insert_operation_run(&self, run: &OperationRun) -> Result<()>

pub fn operation_runs_since(&self, since_ts: &str) -> Result<Vec<OpRunRow>>

Raw rows since a cutoff, for aggregation (incl. source/agent/context dimensions). context is trace-derived — operation_runs has no context column, so it is pulled via a correlated lookup on episodic_log.context_key and is therefore only populated for ops that carry a trace_id (e.g. record); trace-less ops → None.

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

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

Retention: drop run rows older than before_ts (called by curate).

pub fn insert_metric_snapshot(&self, ts: &str, kpis_json: &str) -> Result<()>

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

Most recent snapshot (ts, kpis_json), if any.

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

Recent snapshots newest-first as {ts, kpis:{…}} rows (for the Web trend view).

pub fn snapshot_at_or_before( &self, ts: &str, ) -> Result<Option<(String, String)>>

Nearest snapshot at or before ts — the trend baseline for week-over-week deltas.

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<()>

Insert an episodic_log row if its trace_id does not already exist.

All callers (recall, appraise, record’s fresh-insert branch) pass a newly generated trace_id, so this is an insert in practice. It is INSERT OR IGNORE rather than INSERT OR REPLACE on purpose: REPLACE deletes and re-inserts the whole row, which would silently wipe lifecycle state (distill_state, distill_attempts → 0, distill_last_failed_at → NULL, outcome, usage_state). An accidental re-upsert of an existing trace must never destroy that progress — mutate existing rows through update_episodic_log_state / patch_episodic_log_content instead.

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

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

Recent recall→record trace timeline (newest first) for the Web “Sessions” view. Projects a compact, UI-friendly subset of episodic_log rather than SELECT * so the endpoint stays cheap and stable. Read-only.

pub fn chunk_provenance(&self, chunk_id: &str, limit: usize) -> Result<Value>

Provenance timeline for a single chunk, powering the Web chunk-detail Provenance panel. Read-only projection across usage_trace, feedback_events, chunk_success_traces, and (for distilled chunks) the source episodic_log. Returns:

• events: newest-first merge of per-trace outcomes (task_ok/task_fail, derived from the trace’s chunk-less outcome row) and feedback_up/down events, capped at limit.
• source: the originating episodic_log (query + output_summary) when the chunk is distilled (chunks.distilled_from → episodic_log.id), else null.
• stats + explanation: success/failure/feedback counts, current EMA confidence, and a natural-language confidence summary.

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<()>