Struct Storage 

pub struct Storage { /* private fields */ }

Per-repo Cozo DB handle.

Implementations

impl Storage

pub fn put_symbols(&self, symbols: &[Symbol]) -> Result<()>

Bulk insert symbols using :put with a $rows parameter so user data is bound, not pasted into the script (avoids quote-escape pitfalls).

pub fn gc_symbols_not_in(&self, live_files: &HashSet<String>) -> Result<usize>

Index GC: delete every symbol whose file is NOT in live_files. Also reaps every inbound/outbound edge from those symbols.

Use case: during ckg index, the indexer walks the working tree and produces a fresh symbol set for the files it sees. Files that were indexed previously but have since been renamed or deleted leave phantom Symbol rows that pollute dead-code, orphan-calls, and blast-radius results. Without this sweep, removing a source file silently leaves its symbols behind forever.

live_files is the set of file paths the current index pass produced symbols for. Anything in the Symbol relation with a file not in this set is treated as phantom and dropped.

Returns the count of deleted Symbol rows (edges are deleted as a side-effect via Cozo’s referential rules — see comment below).

pub fn put_edges(&self, edges: &[Edge]) -> Result<()>

Bulk insert edges. Routes by EdgeKind to the right relation.

by_rel groups edges by their Cozo relation name (&'static str from EdgeKind::as_relation()). An enum-keyed array would be marginally faster but EdgeKind variants are few and the BTreeMap overhead is negligible — see L5 tracking comment. Deferring until EdgeKind gains a stable #[repr(u8)] discriminant.

impl Storage

pub fn open_unverified(repo_id: RepoId, base: &Path) -> Result<Self>

Escape hatch — open without recording / verifying a canonical root_path. Use ONLY when the caller has no canonical root available (tests, ad-hoc CLI exploration of a known repo_id, benchmarks).

pub fn open_at(repo_id: RepoId, root_path: &Path, base: &Path) -> Result<Self>

Open or create with canonical root-path verification (I2).

On first init, the canonical path is stamped into Meta. Subsequent opens read it back; if the recorded path doesn’t match we refuse rather than silently merge two repos that happen to hash to the same 96-bit RepoId.

On schema-version mismatch, performs a destructive auto-rebuild. This is intentional for the indexer path, which holds the repo lock. Readers (query/resolve/MCP) should use open_at_readonly instead so they never trigger a destructive rebuild concurrently with an ongoing ckg index.

pub fn open_at_readonly( repo_id: RepoId, root_path: &Path, base: &Path, ) -> Result<Self>

Read-only open: like open_at but never triggers a destructive schema-mismatch rebuild. On version mismatch, returns a clear error directing the user to re-index rather than wiping the DB.

Use this from all reader paths (query, resolve, MCP) so a reader running concurrently with ckg index cannot destroy the indexer’s in-progress write.

impl Storage

pub fn resolve_cross_file_calls(&self) -> Result<usize>

Cross-file resolution pass: for every Calls edge whose dst is a bare name (not an existing symbol id) AND the name matches exactly one Symbol.name in the same repo, rewrite dst to that id.

Returns the number of edges rewritten. Confidence on rewritten edges stays at 0.5 (still ambiguous compared to in-file resolution which gets 1.0 at extract time).

pub fn detect_test_edges(&self) -> Result<usize>

Detect test functions and emit Tests edges to their candidate target.

Rule: any Symbol of kind=function/method whose name starts with test_ is a test. Strip the prefix to get the bare target name. If exactly one other symbol shares that bare name, emit a Tests edge.

Returns the number of Tests edges written.

impl Storage

pub fn repo_id(&self) -> &RepoId

pub fn db_path(&self) -> &Path

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

CR-storage-M-7: returns the currently-recorded Meta.root_path, which may differ from the caller’s input shape if open_at auto- migrated a symlink-equivalent path (canonicalize-equal). Callers that also stamp the path elsewhere (e.g. registry’s Repo.root_path via RegistryStorage::put_repo) should use this accessor so the two authoritative shapes stay consistent.

CR-storage-H3: returns Result<Option<String>> so callers can distinguish “no row recorded” (Ok(None) — fresh DB) from “Meta read failed” (Err — disk error / corruption). Pre-fix the .ok()? collapse made both cases indistinguishable, mirroring the same bug pattern that RootPathProbe::ReadFailed was introduced to fix in lifecycle.rs.

pub fn db(&self) -> &DbInstance

pub fn run_mutable_unchecked(&self, script: &str) -> Result<NamedRows>

Run a Cozo script with mutable access (:put, :rm, :create etc. are allowed). Safety relies on Cozo’s ScriptMutability::Mutable runtime gate — there is no string-level prefilter.

STORAGE-H2 / danger: The name is intentionally verbose. Callers must hold an explicit intent to mutate; prefer Self::run_immutable or Self::run_with_immutable for all read paths and any caller-supplied Datalog (e.g. MCP query tool). This keeps the footprint of mutable execution small and auditable.

pub fn run_immutable(&self, script: &str) -> Result<NamedRows>

Read-only run — passes ScriptMutability::Immutable to Cozo which rejects scripts containing :put, :rm, :create, :replace, :ensure_not, etc. at execution time (not string-prefiltered). Use this for any caller-supplied Datalog (MCP query tool) so a malicious client can’t drop or mutate relations.

pub fn run_with( &self, script: &str, params: BTreeMap<String, DataValue>, ) -> Result<NamedRows>

Mutable run with parameters. Same safety model as Self::run — relies on ScriptMutability::Mutable runtime gate, no string prefilter.

pub fn run_with_immutable( &self, script: &str, params: BTreeMap<String, DataValue>, ) -> Result<NamedRows>

Read-only variant of run_with — caller-supplied params, but the script is rejected if it contains :put / :rm / :create / :replace. Use for any caller-controlled Datalog so a malicious / typo’d script can’t mutate.

pub fn needs_reindex(&self) -> bool

True if this repo was schema-rebuilt and hasn’t been re-indexed since. Set when Storage::open_* triggers rebuild_at_path, cleared via mark_indexed() after a successful ckg index run.

Returns false on any read failure — the sentinel is best-effort UX guidance, not a correctness gate.

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

CR-I-2: Atomicity sentinel. Stamp index_in_progress=true BEFORE the first put_symbols / put_edges of a fresh index run. On next Storage::open, if this flag is still set, needs_reindex is promoted. Cleared by mark_indexed.

pub fn is_index_in_progress(&self) -> bool

CR-I-2: True if a previous index run started but didn’t reach mark_indexed. Mostly internal — Storage::open_at checks this on every open.

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

Clear the needs_reindex AND index_in_progress sentinels after a successful ckg index run. Safe to call when the sentinels are already absent.