Struct SurrealHandle 

pub struct SurrealHandle { /* private fields */ }

SurrealDB connection handle for AIVCS

Implementations

impl SurrealHandle

pub async fn setup_db() -> Result<SurrealHandle, StateError>

Connect to SurrealDB in-memory and set up schema

TDD: test_surreal_connection_and_schema_creation

pub async fn setup_cloud( config: CloudConfig, ) -> Result<SurrealHandle, StateError>

Connect to SurrealDB Cloud

Example

let config = CloudConfig::new(
    "wss://xxx.aws-use1.surrealdb.cloud",
    "your_username",
    "your_password",
);
let handle = SurrealHandle::setup_cloud(config).await?;

pub async fn setup_from_env() -> Result<SurrealHandle, StateError>

Connect using environment variables

If SURREALDB_ENDPOINT is set, connects to cloud. If SURREALDB_URL is set, connects to that URL. Otherwise, falls back to local persistence in .aivcs/db using SurrealKV.

pub async fn save_commit( &self, record: &CommitRecord, ) -> Result<CommitRecord, StateError>

Save a new commit record

pub async fn get_commit( &self, commit_hash: &str, ) -> Result<Option<CommitRecord>, StateError>

Get a commit by its hash

pub async fn save_snapshot( &self, commit_id: &CommitId, state: Value, ) -> Result<(), StateError>

Save a snapshot (agent state)

TDD: test_snapshot_is_atomic_and_retrievable

pub async fn load_snapshot( &self, commit_id: &str, ) -> Result<SnapshotRecord, StateError>

Load a snapshot by commit ID

pub async fn save_commit_graph_edge( &self, child_id: &str, parent_id: &str, ) -> Result<(), StateError>

Save a commit graph edge (parent -> child relationship)

TDD: test_parent_child_edge_is_created

pub async fn get_parent( &self, child_id: &str, ) -> Result<Option<String>, StateError>

Get parent commit ID for a given commit

pub async fn get_children( &self, parent_id: &str, ) -> Result<Vec<String>, StateError>

Get all children of a commit (for branch visualization)

pub async fn save_branch( &self, record: &BranchRecord, ) -> Result<BranchRecord, StateError>

Create or update a branch

pub async fn get_branch( &self, name: &str, ) -> Result<Option<BranchRecord>, StateError>

Get a branch by name

pub async fn get_branch_head( &self, branch_name: &str, ) -> Result<String, StateError>

Get branch head commit ID

pub async fn list_branches(&self) -> Result<Vec<BranchRecord>, StateError>

List all branches

pub async fn delete_branch(&self, name: &str) -> Result<(), StateError>

Delete a branch

pub async fn register_agent( &self, record: &AgentRecord, ) -> Result<AgentRecord, StateError>

Register an agent

pub async fn get_agent( &self, agent_id: &str, ) -> Result<Option<AgentRecord>, StateError>

Get agent by ID

pub async fn save_memory( &self, record: &MemoryRecord, ) -> Result<MemoryRecord, StateError>

Save a memory record

pub async fn get_memories( &self, commit_id: &str, ) -> Result<Vec<MemoryRecord>, StateError>

Get all memories for a commit

pub async fn release_promote( &self, name: &str, spec_digest: &ContentDigest, metadata: ReleaseMetadata, ) -> Result<ReleaseRecord, StorageError>

Promote a new release for an agent.

pub async fn release_rollback( &self, name: &str, ) -> Result<ReleaseRecord, StorageError>

Roll back to the previous release for an agent by re-appending it.

pub async fn release_current( &self, name: &str, ) -> Result<Option<ReleaseRecord>, StorageError>

Get the current release (most recent) for an agent.

pub async fn release_history( &self, name: &str, ) -> Result<Vec<ReleaseRecord>, StorageError>

Get full release history (newest first) for an agent.

pub async fn save_ci_snapshot( &self, snapshot: &CiSnapshot, ) -> Result<String, StateError>

Save a CI snapshot as a content-addressed object.

pub async fn load_ci_snapshot( &self, digest: &str, ) -> Result<Option<CiSnapshot>, StateError>

Load a CI snapshot by digest.

pub async fn save_ci_pipeline( &self, pipeline: &CiPipelineSpec, ) -> Result<String, StateError>

Save a CI pipeline as a content-addressed object.

pub async fn load_ci_pipeline( &self, digest: &str, ) -> Result<Option<CiPipelineSpec>, StateError>

Load a CI pipeline by digest.

pub async fn save_ci_run( &self, run: &CiRunRecord, ) -> Result<CiRunRecord, StateError>

Save a CI run record.

pub async fn get_ci_run( &self, run_id: &str, ) -> Result<Option<CiRunRecord>, StateError>

Get a CI run by run ID.

pub async fn list_ci_runs_by_snapshot( &self, snapshot_digest: &str, ) -> Result<Vec<CiRunRecord>, StateError>

List CI runs for a given snapshot digest.

pub async fn save_decision( &self, record: &DecisionRecord, ) -> Result<DecisionRecord, StateError>

Save a decision record

pub async fn get_decision( &self, decision_id: &str, ) -> Result<Option<DecisionRecord>, StateError>

Get decision by decision ID

pub async fn update_decision_outcome( &self, decision_id: &str, outcome_json: String, ) -> Result<DecisionRecord, StateError>

Update decision outcome by decision ID

pub async fn get_decision_history( &self, task: &str, limit: usize, ) -> Result<Vec<DecisionRecord>, StateError>

Get decision history for a task

pub async fn save_provenance( &self, record: &MemoryProvenanceRecord, ) -> Result<MemoryProvenanceRecord, StateError>

Save a memory provenance record

pub async fn get_provenance( &self, memory_id: &str, ) -> Result<Vec<MemoryProvenanceRecord>, StateError>

Get provenance records for a memory

pub async fn get_commit_history( &self, start_commit: &str, limit: usize, ) -> Result<Vec<CommitRecord>, StateError>

Get commit history (walk back from a commit)

pub async fn get_reasoning_trace( &self, commit_id: &str, ) -> Result<Vec<SnapshotRecord>, StateError>

Get the reasoning trace (CoT) for time-travel debugging

TDD: test_get_trace_for_commit_id_returns_correct_CoT

Trait Implementations

impl Clone for SurrealHandle

fn clone(&self) -> SurrealHandle

Returns a duplicate of the value.

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

Performs copy-assignment from source.