Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(wiki): check session tombstones in reindex transactions
Samir Hanna Verza71ef6118eae8
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex da1fca12..7e101b7a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -12,6 +12,10 @@ version in [`docs/changelog/`](docs/changelog/):## [Unreleased]### Fixed+- Revalidated session-purge tombstones inside the reindex write transaction,+ preventing a queued watcher update from recreating a deleted summary after+ file cleanup failed. Kept surviving manual replacements at the same path+ editable through the watcher (#1439).- Added exact hover timestamps to `/web` page metadata, made the OKF upgradedialog keyboard accessible, and added a labelled main-navigation landmarkwith current-page state and narrow-screen wrapping.diff --git a/crates/ai-memory-store/src/error.rs b/crates/ai-memory-store/src/error.rsindex ebbac1b5..aa86777a 100644--- a/crates/ai-memory-store/src/error.rs+++ b/crates/ai-memory-store/src/error.rs@@ -145,7 +145,7 @@ pub enum StoreError {/// caller-invariant violation).#[error("not found: {0}")]NotFound(String),- /// A late-arriving event named a session that `purge_session` removed.+ /// 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).diff --git a/crates/ai-memory-store/src/ops.rs b/crates/ai-memory-store/src/ops.rsindex 5c5d81e5..10b9a0e6 100644--- a/crates/ai-memory-store/src/ops.rs+++ b/crates/ai-memory-store/src/ops.rs@@ -203,6 +203,55 @@ pub fn upsert_page(conn: &mut Connection, page: &NewPage) -> StoreResult<PageId>Ok(result_id)}+/// Reindex a disk page without reviving a purged session's summary.+/// The tombstone and any surviving manual version are checked in the upsert+/// transaction, so a directory walk's earlier snapshot cannot authorize a+/// write after a session purge. Explicit page writes/restores use `upsert_page`.+pub fn upsert_page_from_disk(conn: &mut Connection, page: &NewPage) -> StoreResult<PageId> {+ let now = Timestamp::now().as_microsecond();+ let tx = conn.transaction()?;+ let session = page+ .path+ .as_str()+ .strip_prefix("sessions/")+ .and_then(|rest| rest.strip_suffix(".md"))+ .and_then(|id| id.parse::<SessionId>().ok());+ if let Some(session) = session {+ let session_text = session.to_string();+ let owns_file = page+ .frontmatter_json+ .get("session_id")+ .and_then(|v| v.as_str())+ == Some(session_text.as_str());+ // #866 keeps manual versions at this path. They may keep changing,+ // but absence of `session_id` alone is not permission to recreate a+ // deleted page: legacy summaries can lack that field too (#701).+ let blocked: bool = tx.query_row(+ "SELECT EXISTS(SELECT 1 FROM purged_sessions \+ WHERE workspace_id = ?1 AND project_id = ?2 AND session_id = ?3) \+ AND (?6 OR NOT EXISTS(SELECT 1 FROM pages \+ WHERE workspace_id = ?1 AND project_id = ?2 AND path = ?4 \+ AND is_latest = 1 \+ AND json_extract(frontmatter_json, '$.session_id') IS NOT ?5))",+ params![+ page.workspace_id.as_bytes(),+ page.project_id.as_bytes(),+ session.as_bytes(),+ page.path.as_str(),+ session_text,+ owns_file+ ],+ |row| row.get(0),+ )?;+ if blocked {+ return Err(StoreError::SessionPurged(session_text));+ }+ }+ let id = upsert_page_in_tx(&tx, page, now)?;+ tx.commit()?;+ Ok(id)+}+/// What a conditional page write requires of the current latest version.#[derive(Debug, Clone, Copy, PartialEq, Eq)]pub enum PagePrecondition {@@ -9233,6 +9282,88 @@ pub(crate) mod tests {assert_eq!(survivor, (manual.as_bytes().to_vec(), false));}+ #[test]+ fn disk_reindex_checks_purge_and_surviving_version_ownership() {+ for (label, manual_before, manual_after, incoming_owned, blocked) in [+ ("owned leftover", false, false, true, true),+ ("legacy leftover", false, false, false, true),+ ("older manual is not live", true, false, false, true),+ ("live manual replacement", false, true, false, false),+ ("summary over live manual", false, true, true, true),+ ] {+ let (_tmp, mut conn, ws, proj) = fresh_db();+ let sid = SessionId::new();+ let path = format!("sessions/{sid}.md");+ begin_session(&mut conn, &hook_session(sid, ws, proj, None)).unwrap();+ if manual_before {+ upsert_page(&mut conn, &page(ws, proj, &path, "older manual")).unwrap();+ }+ let id = upsert_page(&mut conn, &session_page(ws, proj, sid, "summary")).unwrap();+ end_session(&mut conn, &sid, Some(&id)).unwrap();+ if manual_after {+ upsert_page(&mut conn, &page(ws, proj, &path, "manual survivor")).unwrap();+ }+ purge_session(+ &mut conn,+ ws,+ proj,+ sid,+ None,+ Compaction::Skip,+ PurgeMode::Commit,+ )+ .unwrap();+ let disk = if incoming_owned {+ session_page(ws, proj, sid, "rewritten summary")+ } else {+ page(ws, proj, &path, "rewritten manual")+ };+ let rows_before = count(&conn, "SELECT COUNT(*) FROM pages");+ let result = upsert_page_from_disk(&mut conn, &disk);+ if blocked {+ assert!(+ matches!(result, Err(StoreError::SessionPurged(_))),+ "{label}: {result:?}"+ );+ assert_eq!(+ count(&conn, "SELECT COUNT(*) FROM pages"),+ rows_before,+ "{label}"+ );+ } else {+ assert!(result.is_ok(), "{label}: {result:?}");+ }+ // Tombstones are scoped; the same session id in a sibling project+ // and another session's path in this project remain writable.+ let sibling = get_or_create_project(&mut conn, &ws, "sibling", None).unwrap();+ assert!(+ upsert_page_from_disk(&mut conn, &session_page(ws, sibling, sid, "sibling"))+ .is_ok()+ );+ assert!(+ upsert_page_from_disk(+ &mut conn,+ &session_page(ws, proj, SessionId::new(), "other session")+ )+ .is_ok()+ );+ let other_ws = get_or_create_workspace(&mut conn, "other-workspace").unwrap();+ let other_proj = get_or_create_project(&mut conn, &other_ws, "other", None).unwrap();+ assert!(+ upsert_page_from_disk(+ &mut conn,+ &session_page(other_ws, other_proj, sid, "other workspace")+ )+ .is_ok()+ );+ // A session_id on an ordinary content page has never made that+ // page the reserved session summary targeted by this gate.+ let mut note = page(ws, proj, "notes/ordinary.md", "ordinary");+ note.frontmatter_json = serde_json::json!({"session_id": sid.to_string()});+ assert!(upsert_page_from_disk(&mut conn, ¬e).is_ok());+ }+ }+#[test]fn purge_session_keeps_later_manual_page_and_its_wiki_path() {let (_tmp, mut conn, ws, proj) = fresh_db();diff --git a/crates/ai-memory-store/src/writer.rs b/crates/ai-memory-store/src/writer.rsindex 984e5fcb..0e5834e4 100644--- a/crates/ai-memory-store/src/writer.rs+++ b/crates/ai-memory-store/src/writer.rs@@ -174,6 +174,10 @@ pub(crate) enum WriteCmd {page: NewPage,reply: oneshot::Sender<StoreResult<PageId>>,},+ UpsertPageFromDisk {+ page: NewPage,+ reply: oneshot::Sender<StoreResult<PageId>>,+ },UpsertPageIf {page: NewPage,precondition: ops::PagePrecondition,@@ -2772,6 +2776,20 @@ impl WriterHandle {rx.await.map_err(|_| StoreError::WriterClosed)?}+ /// Reindex a disk page, checking session-purge tombstones in the write+ /// transaction. A live manual replacement at a purged session's path is+ /// preserved; a leftover session summary cannot recreate deleted rows.+ ///+ /// # Errors+ /// Returns [`StoreError::SessionPurged`] for a purged summary, or the+ /// writer/SQL errors from [`Self::upsert_page`].+ pub async fn upsert_page_from_disk(&self, page: NewPage) -> StoreResult<PageId> {+ let (tx, rx) = oneshot::channel();+ self.send(WriteCmd::UpsertPageFromDisk { page, reply: tx })+ .await?;+ rx.await.map_err(|_| StoreError::WriterClosed)?+ }+/// [`Self::upsert_page`] only when `precondition` holds for the latest/// version at the page's path, checked in the write's own transaction.///@@ -3851,6 +3869,10 @@ fn worker_loop(mut conn: Connection, mut rx: mpsc::Receiver<WriteCmd>) {let result = ops::upsert_page(&mut conn, &page);send_or_warn(reply, result, "upsert_page");}+ WriteCmd::UpsertPageFromDisk { page, reply } => {+ let result = ops::upsert_page_from_disk(&mut conn, &page);+ send_or_warn(reply, result, "upsert_page_from_disk");+ }WriteCmd::UpsertPageIf {page,precondition,diff --git a/crates/ai-memory-wiki/src/watcher.rs b/crates/ai-memory-wiki/src/watcher.rsindex e1c5203e..7418730a 100644--- a/crates/ai-memory-wiki/src/watcher.rs+++ b/crates/ai-memory-wiki/src/watcher.rs@@ -281,28 +281,11 @@ async fn handle_event(wiki: &Wiki, event: notify_debouncer_full::DebouncedEvent)if is_reserved_page_file(raw_path, &page_path) {continue;}- // A tombstoned session's page must not come back from a file its- // purge could not remove (#701). The path shape decides whether the- // lookup is worth a round trip: only `sessions/<id>.md` can be that- // file, so an ordinary edit to `index.md` or a decision page never- // queries. The sweep paths amortise the same set over a whole- // directory instead; this one sees a single file per event.- if let Some(session) = crate::wiki::session_id_for_page(&page_path) {- match wiki.purged_sessions(ws, proj).await {- Ok(purged) if purged.contains(&session) => {- debug!(path = %page_path, "ignoring event for a purged session page");- continue;- }- Ok(_) => {}- // Fails open, deliberately: a transient lookup error must not- // stop the watcher from indexing edits. The cost of failing- // open here is bounded — the next reconcile pass loads the set- // again and skips the page then.- Err(e) => warn!(path = %page_path, error = %e, "purged-session lookup failed"),- }- }match wiki.reindex_page(ws, proj, page_path.clone()).await {Ok(_) => debug!(path = %page_path, "reindexed via watcher"),+ Err(WikiError::Store(ai_memory_store::StoreError::SessionPurged(_))) => {+ debug!(path = %page_path, "ignoring event for a purged session page");+ }Err(e) => warn!(path = %page_path, error = %e, "watcher reindex failed"),}}@@ -352,21 +335,12 @@ async fn reindex_project_dir(}};- // Fails open for the same reason the single-event path does: a lookup- // error must not stop a directory event from indexing. `Wiki::reindex_all`- // is the one caller that fails closed, because an operator-triggered- // reindex should report the failure rather than quietly skip the gate.- let purged = wiki.purged_sessions(ws, proj).await.unwrap_or_else(|e| {- warn!(error = %e, "purged-session lookup failed; not gating this pass");- std::collections::HashSet::new()- });for path in pages {- if crate::wiki::is_purged_session_page(&path, &purged) {- debug!(path = %path, "skipping a purged session page");- continue;- }match wiki.reindex_page(ws, proj, path.clone()).await {Ok(_) => debug!(path = %path, "reindexed via watcher directory event"),+ Err(WikiError::Store(ai_memory_store::StoreError::SessionPurged(_))) => {+ debug!(path = %path, "skipping a purged session page");+ }Err(e) => warn!(path = %path, error = %e, "watcher directory reindex failed"),}}@@ -693,25 +667,15 @@ async fn reconcile(tokio::task::spawn_blocking(move || walk_markdown_partial(&proj_root)).await.map_err(|e| WikiError::Io(std::io::Error::other(e.to_string())))??;- // Once per directory, not once per page: a project accumulates one- // tombstone per purge, and the set is only consulted for the- // `sessions/<id>.md` paths that a session purge could have left behind.- let purged = wiki.purged_sessions(ws, proj).await?;let mut walked: HashSet<PagePath> = HashSet::with_capacity(pages.len());for path in pages {walked.insert(path.clone());- if crate::wiki::is_purged_session_page(&path, &purged) {- debug!(- path = %path,- "skipping reconcile of a purged (tombstoned) session page",- );- stats.skipped_purged_sessions += 1;- continue;- }- if let Err(e) = wiki.reindex_page(ws, proj, path.clone()).await {- warn!(path = %path, error = %e, "reconcile reindex failed");- } else {- stats.indexed += 1;+ match wiki.reindex_page(ws, proj, path.clone()).await {+ Ok(_) => stats.indexed += 1,+ Err(WikiError::Store(ai_memory_store::StoreError::SessionPurged(_))) => {+ stats.skipped_purged_sessions += 1;+ }+ Err(e) => warn!(path = %path, error = %e, "reconcile reindex failed"),}}@@ -1047,6 +1011,96 @@ mod tests {/// case where the file *outlives* the purge: a cleanup failure is a/// reported, already-tested outcome, and after one the rows are gone while/// the markdown is still on disk. Reverting the tombstone gate fails this.+ #[tokio::test]+ async fn manual_survivor_remains_reindexable_after_session_purge() {+ let (_tmp, store, wiki, ws, proj) = setup().await;+ let sid = ai_memory_core::SessionId::new();+ store+ .writer+ .begin_session(ai_memory_core::NewSession {+ occurred_at: None,+ id: sid,+ workspace_id: ws,+ project_id: proj,+ agent_kind: ai_memory_core::AgentKind::ClaudeCode,+ cwd: None,+ actor_user: None,+ })+ .await+ .unwrap();+ let path = PagePath::new(format!("sessions/{sid}.md")).unwrap();+ let abs = wiki.abs_path(ws, proj, &path);+ std::fs::create_dir_all(abs.parent().unwrap()).unwrap();+ std::fs::write(+ &abs,+ format!("---\ntitle: Session\nsession_id: {sid}\n---\n\noriginalsummarytoken\n"),+ )+ .unwrap();+ let id = wiki.reindex_page(ws, proj, path.clone()).await.unwrap();+ store.writer.end_session(sid, Some(id)).await.unwrap();+ // A manual replacement has no session_id; the store deliberately preserves it (#866).+ std::fs::write(&abs, "---\ntitle: Manual\n---\n\nmanualbeforetoken\n").unwrap();+ wiki.reindex_page(ws, proj, path.clone()).await.unwrap();+ let outcome = wiki+ .purge_session(ws, proj, sid, None, ai_memory_store::Compaction::Skip)+ .await+ .unwrap();+ assert_eq!(outcome.summary.pages_deleted, 1);+ assert!(outcome.summary.removed_paths.is_empty());+ assert!(abs.is_file());+ assert_eq!(+ store+ .reader+ .search_pages("manualbeforetoken".into(), 10, None)+ .await+ .unwrap()+ .len(),+ 1+ );+ for (indexer, token) in [+ ("reconcile", "manualreconciletoken"),+ ("file event", "manualfileeventtoken"),+ ("directory event", "manualdirectorytoken"),+ ("rebuild", "manualrebuildtoken"),+ ] {+ std::fs::write(&abs, format!("---\ntitle: Manual\n---\n\n{token}\n")).unwrap();+ match indexer {+ "reconcile" => {+ let stats = reconcile(&wiki, &mut MissingStreaks::new()).await.unwrap();+ assert_eq!(stats.skipped_purged_sessions, 0);+ }+ "file event" => {+ let event = notify_debouncer_full::DebouncedEvent::new(+ notify::Event::new(EventKind::Modify(notify::event::ModifyKind::Any))+ .add_path(abs.clone()),+ std::time::Instant::now(),+ );+ handle_event(&wiki, event).await;+ }+ "directory event" => {+ assert!(+ reindex_project_dir(&wiki, ws, proj, wiki.project_root(ws, proj)).await+ );+ }+ "rebuild" => {+ let summary = wiki.reindex_all().await.unwrap();+ assert_eq!(summary.skipped_purged_sessions, 0);+ }+ _ => unreachable!(),+ }+ let hits = store+ .reader+ .search_pages(token.into(), 10, None)+ .await+ .unwrap();+ assert_eq!(+ hits.len(),+ 1,+ "{indexer} must keep the preserved manual page editable"+ );+ }+ }+#[tokio::test]async fn purged_session_page_is_not_resurrected_by_a_reconcile_tick() {let (tmp, store, wiki, ws, proj) = setup().await;diff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rsindex e16589cb..1db66595 100644--- a/crates/ai-memory-wiki/src/wiki.rs+++ b/crates/ai-memory-wiki/src/wiki.rs@@ -89,10 +89,9 @@ pub struct ReindexSummary {/// The session a page belongs to, for paths that name one.///-/// Pure path shape, no I/O: only `sessions/<id>.md` can be resurrected by a-/// purge whose file cleanup failed, so this is what decides whether the-/// tombstone set is worth consulting — or, on the single-event path, whether-/// it is worth loading at all.+/// Pure path shape, no I/O. Used to keep session-summary paths out of the+/// missing-file retirement safety net. Reindex ownership and tombstone+/// checks belong to the store transaction, not this path-only classifier.pub(crate) fn session_id_for_page(path: &PagePath) -> Option<SessionId> {path.as_str().strip_prefix("sessions/")@@ -100,18 +99,6 @@ pub(crate) fn session_id_for_page(path: &PagePath) -> Option<SessionId> {.and_then(|id| id.parse::<SessionId>().ok())}-/// Whether `path` is the page of a session this scope has tombstoned.-///-/// For callers that already hold the scope's set. The empty-set and-/// path-shape checks come first so a sweep over a project with no purges-/// never parses an id.-pub(crate) fn is_purged_session_page(path: &PagePath, purged: &HashSet<SessionId>) -> bool {- if purged.is_empty() {- return false;- }- session_id_for_page(path).is_some_and(|id| purged.contains(&id))-}-enum PageStoreRemoval {Delete {author_id: Option<UserId>,@@ -1810,11 +1797,9 @@ impl Wiki {}}- /// Session ids this scope has tombstoned, as a set for the reindex gate.- ///- /// The session-level twin of [`WriterHandle::scope_is_purged`], and read- /// the same way: once per directory per reindex pass, by the callers that- /// walk a tree, rather than once per page (#701).+ /// Session ids this scope has tombstoned, for lifecycle inspection.+ /// Reindex enforces these tombstones in its store write transaction,+ /// rather than authorizing a write from an earlier snapshot of this set.////// # Errors/// Propagates the store error.@@ -2282,7 +2267,7 @@ impl Wiki {let id = self.writer- .upsert_page(NewPage {+ .upsert_page_from_disk(NewPage {workspace_id,project_id,path,@@ -2508,18 +2493,12 @@ impl Wiki {let pages = tokio::task::spawn_blocking(move || crate::watcher::walk_markdown(&pr)).await.map_err(|e| WikiError::Io(std::io::Error::other(e.to_string())))??;- let purged = self.purged_sessions(ws, proj).await?;for path in pages {- if is_purged_session_page(&path, &purged) {- tracing::debug!(- path = %path,- "skipping reindex of a purged (tombstoned) session page",- );- summary.skipped_purged_sessions += 1;- continue;- }match self.reindex_page(ws, proj, path).await {Ok(_) => summary.pages += 1,+ Err(WikiError::Store(ai_memory_store::StoreError::SessionPurged(_))) => {+ summary.skipped_purged_sessions += 1;+ }Err(WikiError::Store(ai_memory_store::StoreError::PagePathCollides {requested,existing,@@ -8466,6 +8445,79 @@ mod tests {(store, wiki, ws, src, dst, sid, path)}+ #[tokio::test]+ async fn reindex_queued_after_purge_rechecks_session_tombstone() {+ let tmp = TempDir::new().unwrap();+ let (store, wiki, ws, proj, _, sid, path) = session_with_page(&tmp).await;+ let page_id = wiki.reindex_page(ws, proj, path.clone()).await.unwrap();+ store.writer.end_session(sid, Some(page_id)).await.unwrap();+ // The watcher's per-directory snapshot predates the purge.+ let snapshot = wiki.purged_sessions(ws, proj).await.unwrap();+ assert!(!snapshot.contains(&sid));+ let abs = wiki.abs_path(ws, proj, &path);+ let raw = std::fs::read(&abs).unwrap();+ let guard = wiki.mutation_lock.read().await;+ let purge = wiki.purge_session(ws, proj, sid, None, ai_memory_store::Compaction::Skip);+ tokio::pin!(purge);+ tokio::select! { biased;+ _ = &mut purge => panic!("purge should wait for the shared guard"),+ _ = std::future::ready(()) => {}+ }+ // A page already admitted by the stale snapshot queues behind the purge.+ let reindex = wiki.reindex_page(ws, proj, path.clone());+ tokio::pin!(reindex);+ tokio::select! { biased;+ _ = &mut reindex => panic!("reindex should wait behind queued purge"),+ _ = std::future::ready(()) => {}+ }+ // Force cleanup failure portably, as the owned-session purge test+ // does. Restore the readable leftover before the queued reindex runs.+ std::fs::remove_file(&abs).unwrap();+ std::fs::create_dir(&abs).unwrap();+ drop(guard);+ let outcome = purge.await.unwrap();+ assert_eq!(outcome.files_failed, vec![path.clone()]);+ std::fs::remove_dir(&abs).unwrap();+ std::fs::write(&abs, raw).unwrap();+ assert!(abs.is_file());+ assert!(+ store+ .reader+ .find_session_scope(sid)+ .await+ .unwrap()+ .is_none()+ );+ assert!(+ store+ .reader+ .search_pages("consolidated".into(), 10, None)+ .await+ .unwrap()+ .is_empty()+ );+ assert!(wiki.purged_sessions(ws, proj).await.unwrap().contains(&sid));+ let reindexed = reindex.await;+ let hits = store+ .reader+ .search_pages("consolidated".into(), 10, None)+ .await+ .unwrap();+ assert!(+ matches!(+ reindexed,+ Err(WikiError::Store(+ ai_memory_store::StoreError::SessionPurged(_)+ ))+ ),+ "{reindexed:?}"+ );+ assert!(+ hits.is_empty(),+ "a reindex queued after purge resurrected the tombstoned session page"+ );+ }+#[tokio::test]async fn purge_session_waits_for_in_flight_reindex_before_deleting_rows() {let tmp = TempDir::new().unwrap();diff --git a/docs/lifecycle-ops.md b/docs/lifecycle-ops.mdindex d926fea8..b3b35fca 100644--- a/docs/lifecycle-ops.md+++ b/docs/lifecycle-ops.md@@ -192,6 +192,15 @@ busy server therefore holds up wiki mutations for longer than the delete itself.The git checkpoints taken before and after the purge sit outside the guard: theybracket it, they do not snapshot it.+Reindex checks session-purge tombstones in the same SQL transaction as its+page write. A watcher event or directory walk that started before a purge+cannot use a stale check to restore a summary left by failed file cleanup.+A manual replacement already preserved by the purge remains reindexable:+the disk page must not name the purged session as its owner, and a live+non-owned version must still exist at that path. A leftover legacy summary+without `session_id` has no such surviving version and stays excluded.+The watcher, its reconciliation pass and `reindex` use the same check.+### Scope containmentThe session id is never authority on its own. Every statement is filtered on