post-cortex-storage 0.5.0

Storage backends for post-cortex — lock-free RocksDB (default) and optional SurrealDB. Implements the Storage trait against the post-cortex domain types.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

// Copyright (c) 2025, 2026 Julius ML
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.

//! SurrealDB storage backend for post-cortex.
//!
//! This module provides a SurrealDB-based storage implementation with:
//! - Native graph support for entity relationships
//! - HNSW vector indexing for embeddings
//! - Efficient session and workspace management
//!
//! Enable with: `cargo build --features surrealdb-storage`
//!
//! Split by trait concern so the public surface stays identical — external
//! code imports `SurrealDBStorage` from `crate::surrealdb_storage`
//! exactly as before.

use std::sync::Arc;
use surrealdb::Surreal;
use surrealdb::engine::any::Any;

mod cards;
mod core;
mod freshness;
mod graph;
mod import_export;
mod messages;
mod records;
mod sessions;
mod text_search;
mod vectors;

#[cfg(test)]
mod persist_tests;
#[cfg(test)]
mod tests;

/// Minimum embedding dimension. Storage doesn't enforce a specific dim —
/// the embedding engine + vector_db (HNSW) own that contract. We keep a
/// sanity floor here to reject malformed zero-length payloads. Each
/// `EmbeddingRecord` carries its `vector.len()` natively in SurrealDB, so
/// callers can mix dims across model migrations as long as they keep the
/// per-session index consistent.
pub(super) const MIN_VECTOR_LEN: usize = 8;

/// SurrealDB storage implementation supporting both local (RocksDB) and remote (WebSocket) backends
#[derive(Clone)]
pub struct SurrealDBStorage {
    pub(super) db: Arc<Surreal<Any>>,
    #[allow(dead_code)]
    pub(super) namespace: String,
    #[allow(dead_code)]
    pub(super) database: String,
    /// What this process last wrote or read per session; lets saves send
    /// only what changed. See [`sessions::PersistedState`].
    pub(super) persisted: Arc<sessions::PersistedStates>,
}

/// The eight relation (edge) tables, one per [`RelationType`].
///
/// [`RelationType`]: post_cortex_core::core::context_update::RelationType
pub(super) const RELATION_TABLES: [(&str, post_cortex_core::core::context_update::RelationType);
    8] = {
    use post_cortex_core::core::context_update::RelationType;
    [
        ("required_by", RelationType::RequiredBy),
        ("leads_to", RelationType::LeadsTo),
        ("related_to", RelationType::RelatedTo),
        ("conflicts_with", RelationType::ConflictsWith),
        ("depends_on", RelationType::DependsOn),
        ("implements", RelationType::Implements),
        ("caused_by", RelationType::CausedBy),
        ("solves", RelationType::Solves),
    ]
};

/// One SurrealQL statement per relation table, built from `template` with
/// `{table}` replaced by the (static) table name. Lets callers touch all
/// eight tables in a single round trip.
pub(super) fn per_relation_table(template: &str) -> String {
    RELATION_TABLES
        .iter()
        .map(|(table, _)| template.replace("{table}", table))
        .collect::<Vec<_>>()
        .join(" ")
}