Struct HistoricalDatabase 

pub struct HistoricalDatabase { /* private fields */ }

Main database handle wrapping a SeaORM connection. All knowledge-graph queries and mutations go through this struct.

Implementations

impl HistoricalDatabase

pub async fn connect(url: &str) -> Result<Self>

Connect to the database and return a new handle. Runs the in-place schema migrations (currently just Self::migrate_schema) so opening a pre-existing KG that predates a column addition silently upgrades to the current shape before any read hits a missing column.

pub async fn begin(&self) -> Result<DatabaseTransaction>

Open a fresh database transaction. Exposed so callers that need to compose multiple write methods atomically can drive the txn lifetime themselves — e.g. workflow learn admits a project via Self::write_project_completed_txn AND then enqueues its new canonicals via Self::enqueue_pending_canonical_semantics_txn in the SAME transaction, so a kill between the two steps rolls back the whole thing.

pub async fn init(&self) -> Result<()>

One-shot lifecycle setup: create tables, run idempotent schema migrations, and seed the static taxonomies. The whole thing runs inside a single transaction so a kill mid-init either leaves the DB completely untouched OR fully set up — never half-seeded. Without this guard, a partial seed (e.g. only 2 of 14 DeFi categories inserted before SIGKILL) would stick because both seed loops short-circuit on if !existing .is_empty(), and write_project_completed later silently drops project_category links for missing category names (db.rs:~2965 just tracing::warn! and continues).

pub async fn schema_is_initialized(&self) -> Result<bool>

Read-only probe for whether this database already holds the historical-KG schema. Consumers (workflow streamloop / autoloop, agentic map-semantics) call this so they can skip the write-requiring Self::init when pointed at a pre-populated DB — including one exposed through a SELECT-only grant (e.g. a read-only MySQL replica), where the CREATE TABLE / ALTER TABLE in init would be denied and is unnecessary. Presence of the project table is the marker: every initialized KG has it, and it’s the first table create_tables emits.

pub async fn migrate_schema(&self) -> Result<()>

Apply every idempotent in-place schema migration this crate knows about. SQLite-only; no-op on other backends since production deployments stick to SQLite for the historical KG. Each individual migration is itself idempotent — calling migrate_schema repeatedly is cheap (a few PRAGMA introspect queries) and safe.

pub async fn export_sql_snapshot(&self) -> Result<String>

pub async fn export_json_snapshot(&self) -> Result<String>

pub async fn import_sql_snapshot(&self, sql: &str) -> Result<usize>

pub async fn import_json_snapshot(&self, json: &str) -> Result<usize>

pub async fn import_knowledge_graph( &self, graph: &KnowledgeGraph, ) -> Result<usize>

pub async fn clobber_into(&self, dst: &HistoricalDatabase) -> Result<usize>

Drop every table in dst, recreate the schema fresh, then copy every row of every table from self into dst inside one destination-side transaction. Source IDs are preserved. Backend-agnostic: source and destination may be different SeaORM backends (sqlite ↔ mysql ↔ postgres) because all I/O goes through the ORM rather than dialect-specific SQL.

pub async fn merge_into(&self, dst: &HistoricalDatabase) -> Result<usize>

Append every row from self into dst without touching dst’s existing rows. Auto-increment PKs are reassigned on insert and every FK is rewritten through an in-memory id map so foreign-key constraints stay intact. Seeded reference tables (category, finding_category) are matched on their natural keys so the dst’s init()-seeded rows are reused instead of duplicated. Caller is responsible for ensuring dst.init() has run before this is invoked.

pub async fn get_project_by_platform_id( &self, platform_id: &str, ) -> Result<Option<Model>>

Find a project by its platform ID (e.g. “c4-420”).

pub async fn get_project_by_name(&self, name: &str) -> Result<Option<Model>>

pub async fn get_project_by_id(&self, id: i32) -> Result<Option<Model>>

pub async fn is_project_completed(&self, platform_id: &str) -> Result<bool>

Check if a project with this platform_id is already completed.

pub async fn get_project_platform( &self, project_id: i32, ) -> Result<Option<Model>>

Get the platform info for a project.

pub async fn set_platform_id( &self, project_id: i32, platform_id: &str, ) -> Result<()>

Set or update the platform ID for a project.

pub async fn list_completed_projects( &self, ) -> Result<Vec<(Model, Option<Model>)>>

pub async fn list_semantics_by_project( &self, project_id: i32, ) -> Result<Vec<(Model, Vec<Model>)>>

pub async fn search_semantics( &self, query: &str, ) -> Result<Vec<(Model, String)>>

pub async fn canonical_semantics_with_children_for_categories( &self, categories: &[DeFiCategory], ) -> Result<Vec<CanonicalWithChildren<Model>>>

Fetch existing canonical semantic nodes (= survivors of any merge) for the given categories, paired with the raw children that have been merged into each canonical. The merge orchestrator renders each canonical with its children so the LLM’s updated_* generalisations can take prior merges into account.

pub async fn existing_semantics_for_categories( &self, categories: &[DeFiCategory], ) -> Result<Vec<Model>>

Fetch existing active semantic nodes for the given categories. Returns nodes that have NOT been merged away.

pub async fn findings_for_semantic_ids( &self, semantic_ids: &[i32], ) -> Result<Vec<LinkedFinding>>

Fetch every finding linked to any of semantic_ids via semantic_finding_link. Returns (semantic_node_id, finding_model) pairs; the same finding may appear multiple times if it is linked to multiple semantics in the input set. Findings linked to any of the given semantic ids OR to any raw (merged-away) semantic that resolves to one of those ids.

Each returned tuple uses the canonical semantic id (one of the inputs) as the first element regardless of whether the link’s source row was on the canonical or on a raw child. This lets callers reason about findings against the canonical they matched on without having to handle merge chains themselves.

pub async fn semantic_link_candidates_for_categories( &self, categories: &[DeFiCategory], ) -> Result<Vec<(Model, i32)>>

pub async fn all_canonical_semantic_link_candidates(&self) -> Result<Vec<Model>>

All canonical semantics across every category, with merged-away aliases excluded. Linking is one-time, so this is the single candidate set we present to the LLM regardless of the pending finding’s project category.

pub async fn load_semantic_scope_seed(&self) -> Result<Vec<SemanticScopeSeed>>

pub async fn load_vulnerability_scope_seed( &self, ) -> Result<Vec<VulnerabilityScopeSeed>>

pub async fn canonical_findings_with_children_for_categories( &self, categories: &[VulnerabilityCategory], ) -> Result<Vec<FindingCanonicalWithTaxonomy>>

Fetch existing canonical findings (= survivors of any merge) for the given vulnerability categories, paired with their taxonomy entry and the raw children that have been merged into each canonical. Mirrors Self::canonical_semantics_with_children_for_categories.

pub async fn existing_findings_for_categories( &self, categories: &[VulnerabilityCategory], ) -> Result<Vec<(Model, Model)>>

pub async fn list_pending_findings_for_linking( &self, ) -> Result<Vec<PendingFindingForLinking>>

pub async fn list_findings_for_linking( &self, include_unlinked: bool, ) -> Result<Vec<PendingFindingForLinking>>

pub async fn write_finding_link_result( &self, result: &PersistedFindingLinkResult, ) -> Result<()>

pub async fn upsert_finding_link_partial( &self, result: &PersistedFindingLinkResult, ) -> Result<()>

Partial-commit hook for the link runner: durably persist the links discovered by ONE batch for this finding. The finding stays out of finding_link_status until [mark_finding_link_complete] runs, so downstream consumers (mapper, spec-gen) skip the still-partial sfl rows via load_knowledge_graph’s gate. Mid-flight crashes leave the sfl rows in place; the next pass re-emits the same edges and the strongest-strength-wins upsert is idempotent.

pub async fn mark_finding_link_complete(&self, finding_id: i32) -> Result<()>

Counterpart to Self::upsert_finding_link_partial: insert the finding_link_status row so downstream consumers start seeing the finding’s links. No-op if the row already exists (resume-safe).

pub async fn list_findings_with_link_status( &self, ) -> Result<Vec<PendingFindingForLinking>>

Findings that have been globally linked already (i.e., have a row in finding_link_status). Used by the retro-link pass to feed the LLM the set of findings that should be re-checked against newly-introduced canonical semantics queued in pending_semantic.

pub async fn list_pending_canonical_semantics(&self) -> Result<Vec<Model>>

Currently-queued canonical semantics waiting for retro-link consideration.

pub async fn append_semantic_finding_links( &self, edges: &[LinkEdge], ) -> Result<usize>

Append (canonical_semantic_id, finding_id, strength, evidence) rows to semantic_finding_link. Idempotent on the composite primary key: existing rows are left untouched (use a separate upsert helper if you need to overwrite strength/evidence; the current write path is append-only). Does NOT touch finding_link_status — retro-link is for findings already there.

pub async fn clear_pending_semantic_queue(&self) -> Result<usize>

Empty the pending_semantic queue. Run after retro-link successfully processed the queued semantics against the existing finding_link_status set.

pub async fn list_processed_findings_without_semantic_links( &self, ) -> Result<Vec<i32>>

pub async fn clear_finding_link_progress(&self) -> Result<(u64, u64)>

pub async fn migrate_link_strength_columns(&self) -> Result<()>

Idempotent migration: bring semantic_finding_link up to the current schema by adding the strength and evidence columns (introduced with the Low/Medium/High LinkStrength rollout) if they aren’t already present. SQLite-only — every existing historical KG lives in SQLite, and ALTER TABLE ... ADD COLUMN is the cheapest way to bolt the new columns onto pre-existing tables without a full data migration.

Safe to call from any DB lifecycle point: skips entirely on non-SQLite backends or when both columns already exist. New DBs created via init() get the columns directly through create_tables, so this method is a no-op for them.

pub async fn validate_db(&self, repair: bool) -> Result<DbValidationReport>

pub async fn write_project_completed( &self, name: &str, platform_id: Option<&str>, categories: &[DeFiCategory], semantic_merge_results: &[MergeResult], finding_merge_results: &[FindingMergeResult], in_project_links: &InProjectLinks, ) -> Result<()>

Atomically write a completed project with its categories, semantic nodes, functions, and merge decisions. Commit one project’s full merge output to the historical KG. Begins its own transaction, calls Self::write_project_completed_txn, commits, and discards the new-canonical id list. Use this when the caller doesn’t need to compose additional writes inside the same transaction; bulk learn paths (learn moves / learn c4 / learn projects) go through here because they don’t run retro-link and therefore don’t need to enqueue pending_semantic.

pub async fn write_project_completed_txn( &self, conn: &DatabaseTransaction, name: &str, platform_id: Option<&str>, categories: &[DeFiCategory], semantic_merge_results: &[MergeResult], finding_merge_results: &[FindingMergeResult], in_project_links: &InProjectLinks, ) -> Result<Vec<i32>>

Transaction-scoped variant of Self::write_project_completed. Writes every row this project contributes (project / project_platform / project_category / semantic_node / semantic_function / semantic_merge / project_semantic / audit_finding / project_finding / audit_finding_category / finding_merge / in-project semantic_finding_link) into the supplied transaction.

Does NOT touch pending_semantic — that side of the “retro-link work queue” is a separate concern and only workflow learn (the incremental flow) calls Self::enqueue_pending_canonical_semantics_txn alongside this. See crates/knowdit/src/cmd/learn/retro_link.rs for the responsibility table.

Returns the canonical semantic ids this project newly introduced (i.e. MergeAction::New entries from the supplied merge results). The caller is responsible for passing them to Self::enqueue_pending_canonical_semantics_txn if their flow runs retro-link.

pub async fn enqueue_pending_canonical_semantics_txn( &self, conn: &DatabaseTransaction, canonical_ids: &[i32], ) -> Result<usize>

Append a list of canonical semantic ids to the pending_semantic retro-link queue, deduping per-id against what’s already enqueued. Called by workflow learn right after Self::write_project_completed_txn inside the SAME transaction so a kill between project commit and queue enqueue rolls both writes back.

Bulk learn paths (learn moves / learn c4 / learn projects) must NOT call this — they never run retro-link, so populating the queue would leave dead rows the validator surfaces as a partial-state issue.

Returns the number of rows actually inserted (i.e. how many of the supplied ids were not already queued).

pub async fn load_knowledge_graph(&self) -> Result<KnowledgeGraph>

Load the full knowledge graph from the database into memory.

Trait Implementations

impl Clone for HistoricalDatabase

fn clone(&self) -> HistoricalDatabase

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for HistoricalDatabase

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.