Crate oxidized_state 

Oxidized-State: SurrealDB Backend for AIVCS

This crate provides the persistence layer for the Agent Version Control System. It handles all I/O with SurrealDB, providing a clean persistence layer for graph states, runs, and memory.

Layer 0 - Data/Persistence

Focus: Data integrity, transactionality, and graph traversal.

Key Components

• SurrealHandle: Manages connection and transactions
• SnapshotRecord: Schema mapping to the Document Layer (State + Memory)
• GraphEdge: Schema mapping to the Graph Layer (Commit -> Parent)
• RunRecord, RunEventRecord: Schema for execution run ledger
• ReleaseRecordSchema: Schema for release management
• init_schema: Initialize all tables with constraints and indexes

Re-exports

pub use migrations::init_schema;

pub use storage_traits::CasStore;

pub use storage_traits::ContentDigest;

pub use storage_traits::ReleaseMetadata;

pub use storage_traits::ReleaseRecord;

pub use storage_traits::ReleaseRegistry;

pub use storage_traits::RunEvent;

pub use storage_traits::RunId;

pub use storage_traits::RunLedger;

pub use storage_traits::RunMetadata;

pub use storage_traits::RunRecord;

pub use storage_traits::RunStatus;

pub use storage_traits::RunSummary;

pub use storage_traits::StorageResult;

pub use surreal_ledger::SurrealRunLedger;

pub use surreal_release_registry::SurrealDbReleaseRegistry;

Modules

fakes

In-memory fakes for storage traits (testing only)

migrations

SurrealDB schema migrations and initialization

storage_traits

Storage trait definitions for AIVCS

surreal_ledger

SurrealDB-backed RunLedger implementation

surreal_release_registry

Structs

AgentRecord

Agent record - registered agent metadata

BranchRecord

Branch record - pointer to a commit

CiArtifact

Metadata for a produced artifact.

CiCommand

A single command to execute inside CI.

CiPipelineSpec

A CI pipeline specification (ordered step list).

CiRunRecord

Durable CI run object (content-linked to snapshot and pipeline).

CiSnapshot

Input snapshot metadata used to identify a CI run context.

CiStepResult

Immutable result for an executed step.

CiStepSpec

Declarative definition for one CI step.

CloudConfig

Configuration for SurrealDB Cloud connection

CommitId

Composite Commit ID - hash of (Logic + State + Environment)

CommitRecord

Commit record stored in SurrealDB

DbRunEventRecord

Run event record - single event in execution

DbRunRecord

Run record - execution run metadata and state

DecisionRecord

Decision record - captures agent decisions with rationale and outcomes

GraphEdge

Graph edge - represents commit relationships (parent -> child)

MemoryProvenanceRecord

Memory provenance record - tracks lineage of memories

MemoryRecord

Memory record - agent memory/context for RAG

ReleaseRecordSchema

Release record - agent release and version management

SnapshotRecord

Snapshot record - the actual agent state data

SurrealHandle

SurrealDB connection handle for AIVCS

Enums

CiRunStatus

Runtime status for a step/run.

ProvenanceSourceType

Provenance source for memory records

StateError

Errors that can occur in the state persistence layer

StorageError

Errors for the storage trait abstractions (CasStore, RunLedger, ReleaseRegistry)

Type Aliases

Result

Result type for oxidized-state operations