Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
//! Store-level error type.
use thiserror::Error;
use ai_memory_core::MemoryError;
/// Which of its keys makes a project answer to an ambiguous name.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AmbiguousMatch {
/// The project's current name.
Name,
/// The canonical path-style key derived from its repository identity.
CanonicalKey,
/// The v2 basename key derived from its repository identity.
LegacyKey,
}
/// One project that answers to an ambiguous name.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AmbiguousProjectHolder {
/// The project's current name, or `None` for a restricted project: the
/// project list hides those names from callers without a grant, and the
/// lookup that fails here runs before any caller is authorized.
pub name: Option<String>,
/// The key that matched.
pub matched_by: AmbiguousMatch,
}
/// The projects behind a [`StoreError::ProjectNameAmbiguous`], rendered as
/// the tail of its message so the operator can see which project to rename,
/// purge or pin with a marker. Empty when the lookup did not collect them.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct AmbiguousProjectHolders(pub Vec<AmbiguousProjectHolder>);
impl std::fmt::Display for AmbiguousProjectHolders {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
let last = self.0.len().saturating_sub(1);
for (index, holder) in self.0.iter().enumerate() {
f.write_str(match index {
0 => ": it is ",
_ if index == last => " and ",
_ => ", ",
})?;
f.write_str(match holder.matched_by {
AmbiguousMatch::Name => "the name of ",
AmbiguousMatch::CanonicalKey => "the canonical key of ",
AmbiguousMatch::LegacyKey => "the legacy key of ",
})?;
match &holder.name {
Some(name) => write!(f, "project '{name}'")?,
None => f.write_str("a restricted project")?,
}
}
Ok(())
}
}
/// Result alias used throughout the store crate.
pub type StoreResult<T> = Result<T, StoreError>;
/// Errors raised by the store layer.
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum StoreError {
/// Underlying SQLite error.
#[error("sqlite: {0}")]
Sqlite(#[from] rusqlite::Error),
/// Migration runner failed.
#[error("migration: {0}")]
Migration(#[from] refinery::Error),
/// A restore source would initialize a new store instead of opening a
/// database that ai-memory already migrated.
#[error(
"backup has no initialized ai-memory database snapshot at db/memory.sqlite; \
restore requires an existing snapshot with applied migration history"
)]
UninitializedSnapshot,
/// The store's schema is newer than this binary: an applied migration is
/// above the highest compiled-in version (refinery reports this as
/// `MissingVersion`). The data was written by a newer ai-memory build than
/// the one now running, so the store is left untouched rather than opened
/// against a schema this binary does not understand. This replaces
/// refinery's misleading raw wording ("migration V… is missing from the
/// filesystem"), which reads as if a file were deleted.
#[error(
"memory database schema is newer than this ai-memory build: the store \
has migration {applied} applied, but this build only ships migrations \
through V{supported}. Run an ai-memory release at least as new as the \
one that wrote this data; a newer store cannot be opened by an older \
binary."
)]
DataSchemaAhead {
/// The applied migration this binary does not know about, formatted as
/// `V{version} ({name})` (e.g. `V28 (sessions_devin_agent_kind)`).
applied: String,
/// The highest schema version this binary ships.
supported: u32,
},
/// An embedded migration is absent from the store's history even though a
/// later version is already applied. Opening remains refused; deciding how
/// to repair a divergent history requires inspecting the actual schema.
#[error(
"memory database migration history has a gap: migration {missing} is \
not recorded, but a later migration is already applied. Back up the \
data directory and report the migration history for review before \
attempting a repair."
)]
MigrationHistoryGap {
/// Missing embedded migration, formatted as `V{version} ({name})`.
missing: String,
},
/// I/O failed (e.g. opening the DB file).
#[error(transparent)]
Io(#[from] std::io::Error),
/// JSON serialisation failure (frontmatter).
#[error("serde: {0}")]
Serde(#[from] serde_json::Error),
/// Writer actor has shut down.
#[error("writer actor is no longer running")]
WriterClosed,
/// The read connection pool was closed at shutdown; no new read opens a
/// connection.
#[error("read connection pool is closed")]
ReaderClosed,
/// A hook tried to reuse a session id that belongs to another immutable
/// session tuple or operator. Deliberately carries no row details.
#[error("session collision")]
SessionCollision,
/// A `spawn_blocking` task panicked or was cancelled.
#[error("reader pool task did not complete: {0}")]
PoolPanic(String),
/// Re-export of [`MemoryError`] for cross-crate propagation.
#[error(transparent)]
Memory(#[from] MemoryError),
/// A project rename was rejected because the destination name is already
/// in use by another project in the same workspace.
#[error("project name '{0}' is already taken in this workspace")]
ProjectNameTaken(String),
/// More than one project in a workspace matched a compatibility name.
#[error("project name '{name}' is ambiguous in this workspace{holders}")]
ProjectNameAmbiguous {
/// The name the caller asked for.
name: String,
/// The projects that answer to it, when the lookup knows them.
holders: AmbiguousProjectHolders,
},
/// The supplied project name failed validation (empty, slash, etc.).
#[error("invalid project name: {0}")]
InvalidProjectName(String),
/// A lookup expected a row that was not present (e.g. moving a project
/// that no longer exists in the source workspace — typically a race or
/// caller-invariant violation).
#[error("not found: {0}")]
NotFound(String),
/// An event or disk reindex named a session that `purge_session` removed.
/// Recreating it would silently undo a deletion the operator already
/// performed and an application may already have reported to a user, so
/// ingest refuses instead (#387).
#[error("session {0} was purged and cannot be recreated")]
SessionPurged(String),
/// A hook named an ID-selected managed run whose boundary refuses it: the
/// run is no longer active, or the hook's agent, owner, native session or
/// checkout does not match the run. A lapsed renewable lease has its own
/// retryable error below. Typed apart from
/// `InvalidState` because the refusal is permanent for that event, so a
/// spool drain must drop it rather than stop behind it (#1892).
#[error("ID-selected managed run boundary mismatch")]
ManagedRunBoundaryRefused,
/// An otherwise-valid ID-selected run is still active but its renewable
/// lease has lapsed. Unlike a terminal boundary refusal, a heartbeat may
/// make the same spooled event valid after a server outage.
#[error("ID-selected managed run lease lapsed")]
ManagedRunLeaseLapsed,
/// A workspace delete was refused because it still holds projects and the
/// caller did not pass `force`. Carries the project count so the admin
/// endpoint / CLI can report it before the operator retries with force.
#[error("workspace still has {0} project(s); pass force to delete anyway")]
WorkspaceNotEmpty(u64),
/// A project purge was rejected because one of its managed workstreams
/// still holds a live run lease. `workstreams` is `ON DELETE CASCADE` from
/// `projects`, and `managed_runs` cascades from `workstreams`, so the
/// purge would delete the lease row out from under a running agent — whose
/// heartbeat then fails with `409 managed run lease is not active` for the
/// rest of the session and whose transcript never reaches the ledger.
/// Carries the offending workstream names so the operator can find the
/// session before retrying with force.
#[error(
"project has {count} active managed run(s) in workstream(s) {workstreams}; \
finish or cancel them first, or pass force to purge anyway (the running \
agent will stop being able to save its history)"
)]
ManagedRunActive {
/// How many `managed_runs` rows are still `state = 'active'`.
count: u64,
/// Comma-separated workstream names holding those runs.
workstreams: String,
},
/// A project merge was refused because sessions can still receive hook
/// observations under the source coordinate.
#[error("project has {count} open session(s); finish them before merging the project")]
ProjectSessionsOpen {
/// Number of source sessions whose `ended_at` is still NULL.
count: u64,
},
/// A workspace rename was rejected because the destination name is already
/// in use by another workspace (`workspaces.name` is UNIQUE).
#[error("workspace name '{0}' is already taken")]
WorkspaceNameTaken(String),
/// A page create was refused because another live page in the same scope
/// differs from it only by case or Unicode normalization. Such a pair is
/// one file on macOS and Windows, so creating the second destroys the
/// first (#1/#2: the index kept both rows and served the survivor's body
/// for either path).
#[error(
"page path '{requested}' collides with existing page '{existing}': they differ only in \
case or Unicode normalization, so a case-insensitive or normalizing filesystem (macOS, \
Windows) stores both at one file and this write would destroy the other page. Choose a \
distinct path, or delete/rename the existing page first."
)]
PagePathCollides {
/// The path this write asked for.
requested: String,
/// The live page it would land on.
existing: String,
},
/// A session move was rejected because the destination scope already has
/// a latest page at the session page path (`idx_pages_latest_path`), so
/// re-stamping the source versions would collide. The caller retries with
/// the regenerate mode or resolves the destination page first.
#[error("page path '{path}' already has a latest version in the destination scope")]
PagePathTaken {
/// The colliding wiki-relative page path.
path: String,
},
/// The supplied workspace name failed validation (empty, slash, etc.).
#[error("invalid workspace name: {0}")]
InvalidWorkspaceName(String),
/// A UNIQUE constraint was violated by an insert (e.g. duplicate
/// `users.username` / `users.email`). The string carries a
/// human-readable explanation the CLI / admin endpoint surfaces
/// verbatim.
#[error("duplicate: {0}")]
Duplicate(String),
/// An OS primitive failed (e.g. the CSPRNG read inside
/// [`crate::users::generate_token`]). Carries the OS error
/// description.
#[error("os error: {0}")]
Os(String),
/// An authenticated finish authority failed an owner or project guard.
#[error("forbidden: {0}")]
Forbidden(&'static str),
/// A persisted row contains malformed data.
#[error("malformed record: {0}")]
MalformedRecord(String),
/// A requested state transition is not allowed.
#[error("invalid state: {0}")]
InvalidState(String),
/// A live `ai-memory run` lease already owns the selected workstream.
#[error("workstream is already active: {0}")]
WorkstreamBusy(String),
/// A workstream rename was rejected because another workstream in the
/// same checkout already holds the destination name. `workstreams` is
/// UNIQUE on (workspace, project, repo, worktree, name), so the rename
/// would violate that constraint; refusing by name gives the caller the
/// collision instead of a bare SQLite error.
#[error("workstream name '{0}' is already taken in this checkout")]
WorkstreamNameTaken(String),
}
impl StoreError {
/// Whether a hook admission failed because its cached scope was deleted or
/// moved after resolution.
#[must_use]
pub fn is_stale_session_scope_reference(&self) -> bool {
let Self::Sqlite(rusqlite::Error::SqliteFailure(error, message)) = self else {
return false;
};
error.code == rusqlite::ErrorCode::ConstraintViolation
&& (error.extended_code == rusqlite::ffi::SQLITE_CONSTRAINT_FOREIGNKEY
|| (error.extended_code == rusqlite::ffi::SQLITE_CONSTRAINT_TRIGGER
&& message.as_deref()
== Some("sessions.workspace_id does not match the project's workspace")))
}
}
#[cfg(test)]
mod tests {
use super::StoreError;
#[test]
fn stale_session_scope_reference_only_matches_fk_or_exact_pairing_trigger() {
let foreign_key = StoreError::Sqlite(rusqlite::Error::SqliteFailure(
rusqlite::ffi::Error {
code: rusqlite::ErrorCode::ConstraintViolation,
extended_code: rusqlite::ffi::SQLITE_CONSTRAINT_FOREIGNKEY,
},
Some("FOREIGN KEY constraint failed".into()),
));
assert!(foreign_key.is_stale_session_scope_reference());
let pairing_trigger = StoreError::Sqlite(rusqlite::Error::SqliteFailure(
rusqlite::ffi::Error {
code: rusqlite::ErrorCode::ConstraintViolation,
extended_code: rusqlite::ffi::SQLITE_CONSTRAINT_TRIGGER,
},
Some("sessions.workspace_id does not match the project's workspace".into()),
));
assert!(pairing_trigger.is_stale_session_scope_reference());
let other_trigger = StoreError::Sqlite(rusqlite::Error::SqliteFailure(
rusqlite::ffi::Error {
code: rusqlite::ErrorCode::ConstraintViolation,
extended_code: rusqlite::ffi::SQLITE_CONSTRAINT_TRIGGER,
},
Some("other trigger".into()),
));
assert!(!other_trigger.is_stale_session_scope_reference());
assert!(!StoreError::SessionCollision.is_stale_session_scope_reference());
assert!(!StoreError::InvalidState("invalid".into()).is_stale_session_scope_reference());
}
}