use async_trait::async_trait;
use chrono::{DateTime, Utc};
use serde_json::Value;
use sqlx::postgres::PgPoolOptions;
use sqlx::{PgPool, Row};
use std::collections::HashMap;
use std::sync::{Arc, Mutex};
use crate::checkpoint::{
encode_delta, fold_chain, materialize_all, Checkpoint, Checkpointer, DeltaEncoding, DeltaHead,
DeltaPolicy,
};
use crate::error::{Result, RustyError};
use crate::journal::ArtifactStore;
use crate::record::{sha256_hex, ArtifactRef, CheckpointHeader, JournalRef};
use crate::state::State;
pub const TABLE_NAME: &str = "rusty_checkpoints";
const CREATE_TABLE_SQL: &str = "\
CREATE TABLE IF NOT EXISTS rusty_checkpoints (
thread_id text NOT NULL,
checkpoint_id text NOT NULL,
step bigint NOT NULL,
state jsonb NOT NULL,
next_nodes jsonb NOT NULL,
created_at timestamptz NOT NULL,
PRIMARY KEY (thread_id, checkpoint_id)
)";
const ADD_HEADER_SQL: &str = "\
ALTER TABLE rusty_checkpoints ADD COLUMN IF NOT EXISTS header jsonb";
const ADD_JOURNAL_REF_SQL: &str = "\
ALTER TABLE rusty_checkpoints ADD COLUMN IF NOT EXISTS journal_ref jsonb";
const ADD_BASE_SQL: &str = "\
ALTER TABLE rusty_checkpoints ADD COLUMN IF NOT EXISTS base text";
const MIGRATION_SQL: &[&str] = &[
CREATE_TABLE_SQL,
ADD_HEADER_SQL,
ADD_JOURNAL_REF_SQL,
ADD_BASE_SQL,
];
const INSERT_SQL: &str = "\
INSERT INTO rusty_checkpoints
(thread_id, checkpoint_id, step, state, next_nodes, created_at, header, journal_ref, base)
VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)";
const GET_LATEST_SQL: &str = "\
SELECT thread_id, checkpoint_id, step, state, next_nodes, created_at, header, journal_ref, base
FROM rusty_checkpoints
WHERE thread_id = $1
ORDER BY created_at DESC, checkpoint_id DESC
LIMIT 1";
const LIST_SQL: &str = "\
SELECT thread_id, checkpoint_id, step, state, next_nodes, created_at, header, journal_ref, base
FROM rusty_checkpoints
WHERE thread_id = $1
ORDER BY step ASC, created_at ASC, checkpoint_id ASC";
const GET_BY_ID_SQL: &str = "\
SELECT thread_id, checkpoint_id, step, state, next_nodes, created_at, header, journal_ref, base
FROM rusty_checkpoints
WHERE thread_id = $1 AND checkpoint_id = $2";
const MIGRATION_LOCK_KEY: i64 = 0x6167_7067_5f6d_6967;
fn map_sqlx_error(op: &str, err: sqlx::Error) -> RustyError {
if let sqlx::Error::Database(db_err) = &err {
if db_err.code().as_deref() == Some("23505") {
return RustyError::Checkpoint(format!(
"{op}: duplicate checkpoint id (unique violation): {db_err}"
));
}
}
RustyError::Checkpoint(format!("{op}: {err}"))
}
#[derive(Debug, Clone, PartialEq)]
struct CheckpointRow {
thread_id: String,
checkpoint_id: String,
step: i64,
state: Value,
next_nodes: Value,
created_at: DateTime<Utc>,
header: Option<Value>,
journal_ref: Option<Value>,
base: Option<String>,
}
impl CheckpointRow {
fn from_checkpoint(checkpoint: &Checkpoint) -> Result<Self> {
let step = i64::try_from(checkpoint.step).map_err(|_| {
RustyError::Checkpoint(format!(
"step {} does not fit into a Postgres bigint",
checkpoint.step
))
})?;
Ok(Self {
thread_id: checkpoint.thread_id.clone(),
checkpoint_id: checkpoint.id.clone(),
step,
state: checkpoint.state.to_value(),
next_nodes: serde_json::to_value(&checkpoint.next_nodes)?,
created_at: checkpoint.created_at,
header: Some(serde_json::to_value(&checkpoint.header)?),
journal_ref: checkpoint
.journal_ref
.as_ref()
.map(serde_json::to_value)
.transpose()?,
base: checkpoint.base.clone(),
})
}
fn from_pg_row(row: &sqlx::postgres::PgRow) -> Result<Self> {
let get = |name: &str| format!("failed to decode column `{name}`");
Ok(Self {
thread_id: row
.try_get("thread_id")
.map_err(|e| map_sqlx_error(&get("thread_id"), e))?,
checkpoint_id: row
.try_get("checkpoint_id")
.map_err(|e| map_sqlx_error(&get("checkpoint_id"), e))?,
step: row
.try_get("step")
.map_err(|e| map_sqlx_error(&get("step"), e))?,
state: row
.try_get("state")
.map_err(|e| map_sqlx_error(&get("state"), e))?,
next_nodes: row
.try_get("next_nodes")
.map_err(|e| map_sqlx_error(&get("next_nodes"), e))?,
created_at: row
.try_get("created_at")
.map_err(|e| map_sqlx_error(&get("created_at"), e))?,
header: row
.try_get("header")
.map_err(|e| map_sqlx_error(&get("header"), e))?,
journal_ref: row
.try_get("journal_ref")
.map_err(|e| map_sqlx_error(&get("journal_ref"), e))?,
base: row
.try_get("base")
.map_err(|e| map_sqlx_error(&get("base"), e))?,
})
}
fn into_checkpoint(self) -> Result<Checkpoint> {
let step = usize::try_from(self.step).map_err(|_| {
RustyError::Checkpoint(format!(
"stored step {} for checkpoint `{}` is negative; cannot map to usize",
self.step, self.checkpoint_id
))
})?;
let state = State::from_value(self.state)?;
let next_nodes: Vec<String> = serde_json::from_value(self.next_nodes)?;
let header = self
.header
.map(serde_json::from_value::<CheckpointHeader>)
.transpose()?
.unwrap_or_default();
let journal_ref = self
.journal_ref
.map(serde_json::from_value::<JournalRef>)
.transpose()?;
Ok(Checkpoint {
id: self.checkpoint_id,
thread_id: self.thread_id,
step,
state,
next_nodes,
created_at: self.created_at,
header,
journal_ref,
base: self.base,
})
}
}
#[derive(Debug, Clone)]
pub struct PostgresCheckpointer {
pool: PgPool,
heads: Arc<Mutex<HashMap<String, DeltaHead>>>,
policy: DeltaPolicy,
}
impl PostgresCheckpointer {
pub async fn connect(url: &str) -> Result<Self> {
let pool = PgPoolOptions::new()
.max_connections(5)
.connect(url)
.await
.map_err(|e| map_sqlx_error("connect", e))?;
let checkpointer = Self::from_pool(pool);
checkpointer.migrate().await?;
Ok(checkpointer)
}
pub fn from_pool(pool: PgPool) -> Self {
Self {
pool,
heads: Arc::new(Mutex::new(HashMap::new())),
policy: DeltaPolicy::default(),
}
}
pub fn with_delta_policy(self, policy: DeltaPolicy) -> Self {
Self { policy, ..self }
}
pub fn delta_policy(&self) -> DeltaPolicy {
self.policy
}
pub async fn delta_head(&self, thread_id: &str) -> Result<Option<DeltaHead>> {
if let Some(head) = self.lock_heads()?.get(thread_id) {
return Ok(Some(head.clone()));
}
let Some(raw) = self.fetch_latest(thread_id).await? else {
return Ok(None);
};
let chain = self.load_chain(thread_id, raw).await?;
let head = DeltaHead {
chain_len: chain.len() - 1,
checkpoint: fold_chain(&chain)?,
};
self.lock_heads()?
.insert(thread_id.to_owned(), head.clone());
Ok(Some(head))
}
fn lock_heads(&self) -> Result<std::sync::MutexGuard<'_, HashMap<String, DeltaHead>>> {
self.heads
.lock()
.map_err(|_| RustyError::Checkpoint("delta-head cache poisoned".into()))
}
async fn fetch_latest(&self, thread_id: &str) -> Result<Option<Checkpoint>> {
let row = sqlx::query(GET_LATEST_SQL)
.bind(thread_id)
.fetch_optional(&self.pool)
.await
.map_err(|e| map_sqlx_error("get latest checkpoint", e))?;
row.map(|r| CheckpointRow::from_pg_row(&r).and_then(CheckpointRow::into_checkpoint))
.transpose()
}
async fn fetch_raw(&self, thread_id: &str, checkpoint_id: &str) -> Result<Option<Checkpoint>> {
let row = sqlx::query(GET_BY_ID_SQL)
.bind(thread_id)
.bind(checkpoint_id)
.fetch_optional(&self.pool)
.await
.map_err(|e| map_sqlx_error("get checkpoint by id", e))?;
row.map(|r| CheckpointRow::from_pg_row(&r).and_then(CheckpointRow::into_checkpoint))
.transpose()
}
async fn load_chain(&self, thread_id: &str, tip: Checkpoint) -> Result<Vec<Checkpoint>> {
let fold_bound = self.policy.max_chain_len.saturating_mul(4).max(128);
let mut chain = vec![tip];
let mut visited = std::collections::HashSet::new();
while let Some(base_id) = chain.last().expect("chain starts non-empty").base.clone() {
if !visited.insert(base_id.clone()) {
return Err(RustyError::Checkpoint(format!(
"checkpoint delta chain in thread `{thread_id}` has a cycle at `{base_id}`"
)));
}
if chain.len() > fold_bound {
return Err(RustyError::Checkpoint(format!(
"checkpoint delta chain in thread `{thread_id}` exceeds {fold_bound} links; \
refusing to fold (write bound is {})",
self.policy.max_chain_len
)));
}
let base = self.fetch_raw(thread_id, &base_id).await?.ok_or_else(|| {
RustyError::Checkpoint(format!(
"checkpoint delta chain in thread `{thread_id}` is broken: \
base `{base_id}` does not exist"
))
})?;
chain.push(base);
}
chain.reverse();
Ok(chain)
}
async fn materialize(&self, thread_id: &str, raw: Checkpoint) -> Result<Checkpoint> {
if raw.base.is_none() {
return Ok(raw);
}
let chain = self.load_chain(thread_id, raw).await?;
fold_chain(&chain)
}
async fn put_internal(&self, checkpoint: Checkpoint, force_full: bool) -> Result<()> {
let encoding = if force_full {
DeltaEncoding::full(&checkpoint)
} else {
let head = self.delta_head(&checkpoint.thread_id).await?;
encode_delta(&checkpoint, head.as_ref(), &self.policy)
};
let row = CheckpointRow::from_checkpoint(&encoding.checkpoint)?;
sqlx::query(INSERT_SQL)
.bind(&row.thread_id)
.bind(&row.checkpoint_id)
.bind(row.step)
.bind(&row.state)
.bind(&row.next_nodes)
.bind(row.created_at)
.bind(&row.header)
.bind(&row.journal_ref)
.bind(&row.base)
.execute(&self.pool)
.await
.map_err(|e| map_sqlx_error("put checkpoint", e))?;
self.lock_heads()?.insert(
checkpoint.thread_id.clone(),
DeltaHead {
checkpoint,
chain_len: encoding.chain_len,
},
);
Ok(())
}
pub async fn migrate(&self) -> Result<()> {
let mut tx = self
.pool
.begin()
.await
.map_err(|e| map_sqlx_error("migrate", e))?;
sqlx::query("SELECT pg_advisory_xact_lock($1)")
.bind(MIGRATION_LOCK_KEY)
.execute(&mut *tx)
.await
.map_err(|e| map_sqlx_error("migrate", e))?;
for statement in MIGRATION_SQL {
sqlx::query(statement)
.execute(&mut *tx)
.await
.map_err(|e| map_sqlx_error("migrate", e))?;
}
tx.commit()
.await
.map_err(|e| map_sqlx_error("migrate", e))?;
Ok(())
}
pub fn pool(&self) -> &PgPool {
&self.pool
}
}
pub const ARTIFACTS_TABLE_NAME: &str = "rusty_artifacts";
const CREATE_ARTIFACTS_TABLE_SQL: &str = "\
CREATE TABLE IF NOT EXISTS rusty_artifacts (
sha256 text NOT NULL PRIMARY KEY,
payload bytea NOT NULL,
created_at timestamptz NOT NULL
)";
const INSERT_ARTIFACT_SQL: &str = "\
INSERT INTO rusty_artifacts (sha256, payload, created_at)
VALUES ($1, $2, $3)
ON CONFLICT (sha256) DO NOTHING";
const GET_ARTIFACT_SQL: &str = "\
SELECT payload FROM rusty_artifacts WHERE sha256 = $1";
const HAS_ARTIFACT_SQL: &str = "\
SELECT EXISTS (SELECT 1 FROM rusty_artifacts WHERE sha256 = $1)";
#[derive(Debug, Clone)]
pub struct PostgresArtifactStore {
pool: PgPool,
}
impl PostgresArtifactStore {
pub async fn connect(url: &str) -> Result<Self> {
let pool = PgPoolOptions::new()
.max_connections(5)
.connect(url)
.await
.map_err(|e| map_sqlx_error("connect", e))?;
let store = Self { pool };
store.migrate().await?;
Ok(store)
}
pub fn from_pool(pool: PgPool) -> Self {
Self { pool }
}
pub async fn migrate(&self) -> Result<()> {
sqlx::query(CREATE_ARTIFACTS_TABLE_SQL)
.execute(&self.pool)
.await
.map_err(|e| map_sqlx_error("migrate artifacts table", e))?;
Ok(())
}
pub fn pool(&self) -> &PgPool {
&self.pool
}
}
#[async_trait]
impl ArtifactStore for PostgresArtifactStore {
async fn put(&self, bytes: &[u8]) -> Result<ArtifactRef> {
let reference = ArtifactRef {
sha256: sha256_hex(bytes),
bytes: bytes.len() as u64,
};
sqlx::query(INSERT_ARTIFACT_SQL)
.bind(&reference.sha256)
.bind(bytes)
.bind(Utc::now())
.execute(&self.pool)
.await
.map_err(|e| map_sqlx_error("put artifact", e))?;
Ok(reference)
}
async fn get(&self, sha256: &str) -> Result<Vec<u8>> {
let row = sqlx::query(GET_ARTIFACT_SQL)
.bind(sha256)
.fetch_optional(&self.pool)
.await
.map_err(|e| map_sqlx_error("get artifact", e))?;
let bytes: Vec<u8> = row
.map(|r| r.try_get("payload"))
.transpose()
.map_err(|e| map_sqlx_error("decode artifact payload", e))?
.ok_or_else(|| RustyError::Checkpoint(format!("artifact `{sha256}` does not exist")))?;
let actual = sha256_hex(&bytes);
if actual != sha256 {
return Err(RustyError::Serialization(serde_json::Error::io(
std::io::Error::new(
std::io::ErrorKind::InvalidData,
format!(
"artifact integrity failure: `{sha256}` re-hashes to `{actual}`; \
the stored bytes are corrupt"
),
),
)));
}
Ok(bytes)
}
async fn contains(&self, sha256: &str) -> Result<bool> {
sqlx::query_scalar(HAS_ARTIFACT_SQL)
.bind(sha256)
.fetch_one(&self.pool)
.await
.map_err(|e| map_sqlx_error("check artifact", e))
}
}
#[async_trait]
impl Checkpointer for PostgresCheckpointer {
async fn put(&self, checkpoint: Checkpoint) -> Result<()> {
self.put_internal(checkpoint, false).await
}
async fn get_latest(&self, thread_id: &str) -> Result<Option<Checkpoint>> {
let Some(raw) = self.fetch_latest(thread_id).await? else {
return Ok(None);
};
self.materialize(thread_id, raw).await.map(Some)
}
async fn list(&self, thread_id: &str) -> Result<Vec<Checkpoint>> {
let rows = sqlx::query(LIST_SQL)
.bind(thread_id)
.fetch_all(&self.pool)
.await
.map_err(|e| map_sqlx_error("list checkpoints", e))?;
let raw: Vec<Checkpoint> = rows
.iter()
.map(|r| CheckpointRow::from_pg_row(r).and_then(CheckpointRow::into_checkpoint))
.collect::<Result<_>>()?;
let mut all = materialize_all(raw);
all.sort_by(|a, b| {
a.step
.cmp(&b.step)
.then(a.created_at.cmp(&b.created_at))
.then(a.id.cmp(&b.id))
});
Ok(all)
}
async fn get_by_id(&self, thread_id: &str, checkpoint_id: &str) -> Result<Option<Checkpoint>> {
let Some(raw) = self.fetch_raw(thread_id, checkpoint_id).await? else {
return Ok(None);
};
self.materialize(thread_id, raw).await.map(Some)
}
async fn fork_thread(
&self,
src_thread: &str,
dst_thread: &str,
at_checkpoint_id: Option<&str>,
) -> Result<usize> {
if src_thread == dst_thread {
return Err(RustyError::Checkpoint(format!(
"cannot fork thread `{src_thread}` onto itself: checkpoint ids would collide"
)));
}
let all = self.list(src_thread).await?;
if all.is_empty() {
return Err(RustyError::Checkpoint(format!(
"cannot fork thread `{src_thread}`: no checkpoints found"
)));
}
let selected: Vec<Checkpoint> = match at_checkpoint_id {
None => all,
Some(id) => {
let pos = all.iter().position(|c| c.id == id).ok_or_else(|| {
RustyError::Checkpoint(format!(
"cannot fork thread `{src_thread}`: unknown checkpoint id `{id}`"
))
})?;
all[..=pos].to_vec()
}
};
let copied = selected.len();
for mut checkpoint in selected {
checkpoint.thread_id = dst_thread.to_string();
checkpoint.base = None;
self.put_internal(checkpoint, true).await?;
}
tracing::info!(
src_thread = %src_thread,
dst_thread = %dst_thread,
copied = copied,
"thread history forked"
);
Ok(copied)
}
}
#[cfg(test)]
mod tests {
use super::*;
fn sample_checkpoint() -> Checkpoint {
let mut state = State::new();
state.insert("answer", serde_json::json!(42));
state.insert(
"messages",
serde_json::json!([{"role": "user", "content": "hi"}]),
);
Checkpoint::new("thread-1", 3, state, vec!["node_b".into(), "node_c".into()])
}
#[test]
fn create_table_sql_matches_schema_contract() {
assert!(CREATE_TABLE_SQL.starts_with("CREATE TABLE IF NOT EXISTS rusty_checkpoints"));
for column in [
"thread_id text",
"checkpoint_id text",
"step bigint",
"state jsonb",
"next_nodes jsonb",
"created_at timestamptz",
"PRIMARY KEY (thread_id, checkpoint_id)",
] {
assert!(
CREATE_TABLE_SQL.contains(column),
"migration SQL is missing `{column}`:\n{CREATE_TABLE_SQL}"
);
}
}
#[test]
fn insert_sql_binds_all_columns_without_upsert() {
assert!(INSERT_SQL.starts_with("INSERT INTO rusty_checkpoints"));
assert!(INSERT_SQL.contains(
"(thread_id, checkpoint_id, step, state, next_nodes, created_at, header, journal_ref, base)"
));
assert!(INSERT_SQL.contains("VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)"));
assert!(!INSERT_SQL.to_uppercase().contains("ON CONFLICT"));
}
#[test]
fn migration_is_create_then_additive_idempotent_alters() {
assert_eq!(MIGRATION_SQL.len(), 4);
assert!(MIGRATION_SQL[0].starts_with("CREATE TABLE IF NOT EXISTS rusty_checkpoints"));
assert!(MIGRATION_SQL[1].contains("ADD COLUMN IF NOT EXISTS header jsonb"));
assert!(MIGRATION_SQL[2].contains("ADD COLUMN IF NOT EXISTS journal_ref jsonb"));
assert!(MIGRATION_SQL[3].contains("ADD COLUMN IF NOT EXISTS base text"));
for statement in MIGRATION_SQL {
assert!(
statement.to_uppercase().contains("IF NOT EXISTS"),
"migration statement must be idempotent: {statement}"
);
assert!(
statement.contains("rusty_checkpoints"),
"migration statement must target the checkpoints table: {statement}"
);
}
for statement in &MIGRATION_SQL[1..] {
let upper = statement.to_uppercase();
assert!(upper.starts_with("ALTER TABLE"));
assert!(!upper.contains("DROP"), "got: {statement}");
assert!(!upper.contains("NOT NULL"), "got: {statement}");
}
}
#[test]
fn get_latest_sql_uses_insertion_order_recency() {
assert!(GET_LATEST_SQL.contains("WHERE thread_id = $1"));
assert!(GET_LATEST_SQL.contains("ORDER BY created_at DESC, checkpoint_id DESC"));
assert!(!GET_LATEST_SQL.contains("step DESC"));
assert!(GET_LATEST_SQL.contains("LIMIT 1"));
}
#[test]
fn list_sql_orders_by_step_with_total_tie_break() {
assert!(LIST_SQL.contains("WHERE thread_id = $1"));
assert!(LIST_SQL.contains("ORDER BY step ASC, created_at ASC, checkpoint_id ASC"));
assert!(!LIST_SQL.contains("LIMIT"));
}
#[test]
fn get_by_id_sql_is_a_primary_key_point_lookup() {
assert!(GET_BY_ID_SQL.contains("WHERE thread_id = $1 AND checkpoint_id = $2"));
assert!(GET_BY_ID_SQL.starts_with("SELECT"));
}
#[test]
fn read_statements_select_the_r05_columns() {
for sql in [GET_LATEST_SQL, LIST_SQL, GET_BY_ID_SQL] {
assert!(
sql.contains("header"),
"statement must read `header`: {sql}"
);
assert!(
sql.contains("journal_ref"),
"statement must read `journal_ref`: {sql}"
);
assert!(sql.contains("base"), "statement must read `base`: {sql}");
assert!(!sql.contains("SELECT *"), "got: {sql}");
}
}
#[test]
fn statements_use_bound_parameters_only() {
for sql in [INSERT_SQL, GET_LATEST_SQL, LIST_SQL, GET_BY_ID_SQL] {
assert!(sql.contains("$1"), "statement must bind parameters: {sql}");
}
}
#[test]
fn checkpoint_row_roundtrip_preserves_all_fields() {
let checkpoint = sample_checkpoint();
let row = CheckpointRow::from_checkpoint(&checkpoint).unwrap();
assert_eq!(row.thread_id, checkpoint.thread_id);
assert_eq!(row.checkpoint_id, checkpoint.id);
assert_eq!(row.step, checkpoint.step as i64);
assert!(row.state.is_object());
assert!(row.next_nodes.is_array());
let back = row.into_checkpoint().unwrap();
assert_eq!(back.id, checkpoint.id);
assert_eq!(back.thread_id, checkpoint.thread_id);
assert_eq!(back.step, checkpoint.step);
assert_eq!(back.state, checkpoint.state);
assert_eq!(back.next_nodes, checkpoint.next_nodes);
assert_eq!(back.created_at, checkpoint.created_at);
assert_eq!(back.header, checkpoint.header);
assert_eq!(back.journal_ref, checkpoint.journal_ref);
}
#[test]
fn checkpoint_row_roundtrip_preserves_header_and_journal_ref() {
let mut checkpoint = sample_checkpoint();
checkpoint.header = CheckpointHeader {
format_version: crate::record::CURRENT_FORMAT_VERSION,
graph_version: "react-v3".into(),
graph_hash: "5d41402abc4b2a76b9719d911017c592".into(),
policy_version: Default::default(),
logical_clock: 1_700_000_000_042,
manifest: None,
};
checkpoint.journal_ref = Some(JournalRef {
events: 17,
sha256: "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08".into(),
});
let row = CheckpointRow::from_checkpoint(&checkpoint).unwrap();
assert_eq!(
row.header.as_ref().and_then(|h| h.get("graph_version")),
Some(&serde_json::json!("react-v3"))
);
assert_eq!(
row.journal_ref.as_ref().and_then(|r| r.get("events")),
Some(&serde_json::json!(17))
);
let back = row.into_checkpoint().unwrap();
assert_eq!(back.header, checkpoint.header);
assert_eq!(back.journal_ref, checkpoint.journal_ref);
}
#[test]
fn null_r05_columns_decode_to_serde_defaults() {
let mut row = CheckpointRow::from_checkpoint(&sample_checkpoint()).unwrap();
row.header = None;
row.journal_ref = None;
let back = row.into_checkpoint().unwrap();
assert_eq!(back.header, CheckpointHeader::default());
assert_eq!(back.journal_ref, None);
}
#[test]
fn base_column_roundtrips_and_null_decodes_to_full_snapshot() {
let mut checkpoint = sample_checkpoint();
assert_eq!(checkpoint.base, None);
let row = CheckpointRow::from_checkpoint(&checkpoint).unwrap();
assert_eq!(row.base, None);
assert_eq!(row.into_checkpoint().unwrap().base, None);
checkpoint.base = Some("parent-checkpoint-id".into());
let row = CheckpointRow::from_checkpoint(&checkpoint).unwrap();
assert_eq!(row.base.as_deref(), Some("parent-checkpoint-id"));
assert_eq!(
row.into_checkpoint().unwrap().base.as_deref(),
Some("parent-checkpoint-id")
);
}
#[test]
fn artifact_statements_are_idempotent_and_bound() {
assert!(
CREATE_ARTIFACTS_TABLE_SQL.starts_with("CREATE TABLE IF NOT EXISTS rusty_artifacts")
);
for column in ["sha256", "payload", "created_at"] {
assert!(
CREATE_ARTIFACTS_TABLE_SQL.contains(column),
"artifact table is missing `{column}`"
);
}
assert!(INSERT_ARTIFACT_SQL.contains("ON CONFLICT (sha256) DO NOTHING"));
for sql in [INSERT_ARTIFACT_SQL, GET_ARTIFACT_SQL, HAS_ARTIFACT_SQL] {
assert!(sql.contains("$1"), "statement must bind parameters: {sql}");
assert!(!sql.contains("SELECT *"), "got: {sql}");
}
}
#[test]
fn malformed_header_json_is_rejected() {
let mut row = CheckpointRow::from_checkpoint(&sample_checkpoint()).unwrap();
row.header = Some(serde_json::json!({"format_version": "not-a-number"}));
assert!(row.into_checkpoint().is_err());
}
#[test]
fn row_with_negative_step_is_rejected() {
let mut row = CheckpointRow::from_checkpoint(&sample_checkpoint()).unwrap();
row.step = -1;
let err = row.into_checkpoint().unwrap_err();
assert!(matches!(err, RustyError::Checkpoint(_)));
}
#[test]
fn row_with_non_object_state_is_rejected() {
let mut row = CheckpointRow::from_checkpoint(&sample_checkpoint()).unwrap();
row.state = serde_json::json!([1, 2, 3]);
assert!(row.into_checkpoint().is_err());
}
#[test]
fn row_with_non_array_next_nodes_is_rejected() {
let mut row = CheckpointRow::from_checkpoint(&sample_checkpoint()).unwrap();
row.next_nodes = serde_json::json!("not-an-array");
assert!(row.into_checkpoint().is_err());
}
#[tokio::test]
#[ignore = "requires a live Postgres; set DATABASE_URL to run"]
async fn postgres_live_roundtrip() {
let Ok(url) = std::env::var("DATABASE_URL") else {
eprintln!("DATABASE_URL not set; skipping live Postgres test");
return;
};
let store = PostgresCheckpointer::connect(&url).await.unwrap();
for column in ["header", "journal_ref"] {
let present: bool = sqlx::query_scalar(
"SELECT EXISTS (
SELECT 1 FROM information_schema.columns
WHERE table_name = 'rusty_checkpoints' AND column_name = $1
)",
)
.bind(column)
.fetch_one(store.pool())
.await
.unwrap();
assert!(present, "migration must add column `{column}`");
}
let thread = format!("test-{}", uuid::Uuid::new_v4());
assert!(store.get_latest(&thread).await.unwrap().is_none());
assert!(store.list(&thread).await.unwrap().is_empty());
let cp0 = sample_checkpoint_with(&thread, 0);
let cp1 = sample_checkpoint_with(&thread, 1);
store.put(cp0.clone()).await.unwrap();
store.put(cp1.clone()).await.unwrap();
let latest = store.get_latest(&thread).await.unwrap().unwrap();
assert_eq!(latest.id, cp1.id);
let all = store.list(&thread).await.unwrap();
assert_eq!(all.len(), 2);
assert_eq!(all[0].id, cp0.id);
assert_eq!(all[1].id, cp1.id);
assert_eq!(all[0].state, cp0.state);
assert_eq!(all[1].next_nodes, cp1.next_nodes);
let err = store.put(cp1).await.unwrap_err();
assert!(matches!(err, RustyError::Checkpoint(_)));
let mut cp2 = sample_checkpoint_with(&thread, 2);
cp2.header.graph_version = "live-test-v1".into();
cp2.header.graph_hash = "5d41402abc4b2a76b9719d911017c592".into();
cp2.header.logical_clock = 42;
cp2.journal_ref = Some(JournalRef {
events: 9,
sha256: "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08".into(),
});
store.put(cp2.clone()).await.unwrap();
let back = store
.get_by_id(&thread, &cp2.id)
.await
.unwrap()
.expect("checkpoint stored above");
assert_eq!(back.header, cp2.header);
assert_eq!(back.journal_ref, cp2.journal_ref);
let cp3 = sample_checkpoint_with(&thread, 3);
sqlx::query(
"INSERT INTO rusty_checkpoints
(thread_id, checkpoint_id, step, state, next_nodes, created_at)
VALUES ($1, $2, $3, $4, $5, $6)",
)
.bind(&cp3.thread_id)
.bind(&cp3.id)
.bind(cp3.step as i64)
.bind(cp3.state.to_value())
.bind(serde_json::to_value(&cp3.next_nodes).unwrap())
.bind(cp3.created_at)
.execute(store.pool())
.await
.unwrap();
let back = store
.get_by_id(&thread, &cp3.id)
.await
.unwrap()
.expect("legacy row inserted above");
assert_eq!(back.header, CheckpointHeader::default());
assert_eq!(back.journal_ref, None);
let delta_thread = format!("test-delta-{}", uuid::Uuid::new_v4());
let blob = "x".repeat(4096);
let mut state_a = State::new();
state_a.insert("blob", serde_json::json!(blob));
state_a.insert("answer", serde_json::json!(0));
let cp_a = Checkpoint::new(&delta_thread, 0, state_a, vec!["next".into()]);
let mut state_b = State::new();
state_b.insert("blob", serde_json::json!(blob));
state_b.insert("answer", serde_json::json!(1));
let cp_b = Checkpoint::new(&delta_thread, 1, state_b, vec!["next".into()]);
store.put(cp_a.clone()).await.unwrap();
store.put(cp_b.clone()).await.unwrap();
let (raw_base, raw_state): (Option<String>, Value) = sqlx::query_as(
"SELECT base, state FROM rusty_checkpoints
WHERE thread_id = $1 AND checkpoint_id = $2",
)
.bind(&delta_thread)
.bind(&cp_b.id)
.fetch_one(store.pool())
.await
.unwrap();
assert_eq!(raw_base.as_deref(), Some(cp_a.id.as_str()));
assert!(raw_state.get("answer").is_some());
assert!(
raw_state.get("blob").is_none(),
"delta row must not re-store the unchanged channel: {raw_state}"
);
let latest = store.get_latest(&delta_thread).await.unwrap().unwrap();
assert_eq!(latest.id, cp_b.id);
assert_eq!(latest.state, cp_b.state);
assert_eq!(latest.base, None);
let folded = store
.get_by_id(&delta_thread, &cp_b.id)
.await
.unwrap()
.unwrap();
assert_eq!(folded.state, cp_b.state);
let fork_thread = format!("test-fork-{}", uuid::Uuid::new_v4());
let copied = store
.fork_thread(&delta_thread, &fork_thread, None)
.await
.unwrap();
assert_eq!(copied, 2);
let dangling: i64 = sqlx::query_scalar(
"SELECT COUNT(*) FROM rusty_checkpoints
WHERE thread_id = $1 AND base IS NOT NULL",
)
.bind(&fork_thread)
.fetch_one(store.pool())
.await
.unwrap();
assert_eq!(dangling, 0, "fork must write full snapshots only");
let forked_latest = store.get_latest(&fork_thread).await.unwrap().unwrap();
assert_eq!(forked_latest.state, cp_b.state);
let artifacts = PostgresArtifactStore::from_pool(store.pool().clone());
artifacts.migrate().await.unwrap();
let payload = b"live-test artifact payload".to_vec();
let reference = artifacts.put(&payload).await.unwrap();
assert!(artifacts.contains(&reference.sha256).await.unwrap());
assert_eq!(artifacts.get(&reference.sha256).await.unwrap(), payload);
let again = artifacts.put(&payload).await.unwrap();
assert_eq!(again, reference);
let rows: i64 =
sqlx::query_scalar("SELECT COUNT(*) FROM rusty_artifacts WHERE sha256 = $1")
.bind(&reference.sha256)
.fetch_one(store.pool())
.await
.unwrap();
assert_eq!(rows, 1);
sqlx::query("UPDATE rusty_artifacts SET payload = $2 WHERE sha256 = $1")
.bind(&reference.sha256)
.bind(b"tampered".as_slice())
.execute(store.pool())
.await
.unwrap();
assert!(artifacts.get(&reference.sha256).await.is_err());
sqlx::query("DELETE FROM rusty_checkpoints WHERE thread_id = ANY($1)")
.bind(vec![thread, delta_thread, fork_thread])
.execute(store.pool())
.await
.unwrap();
sqlx::query("DELETE FROM rusty_artifacts WHERE sha256 = $1")
.bind(&reference.sha256)
.execute(store.pool())
.await
.unwrap();
}
fn sample_checkpoint_with(thread: &str, step: usize) -> Checkpoint {
let mut state = State::new();
state.insert("answer", serde_json::json!(step));
Checkpoint::new(thread, step, state, vec!["next".into()])
}
}