Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

fix(admin): harden workspace delete lifecycle

AkitaOnRailsd0430450a47f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 602ad049..88d6a75f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Changed
+- `/admin/delete-workspace` now runs `purge_workspace` admission before
+ destructive work, reports filesystem partial failures in `files_failed`, and
+ notifies non-blocking mirrors after durable deletion; `/admin/rename-workspace`
+ refreshes scope manifests after the SQLite rename.
- OIDC CLI help and token-store test fixtures now use a neutral `ai-memory`
realm placeholder instead of the old project-specific `serpro` example, and
the unused LLM retry-exhaustion error variant was removed ([#171]).
diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rs
index 99334d12..5a9dbb1d 100644
--- a/crates/ai-memory-mcp/src/admin.rs
+++ b/crates/ai-memory-mcp/src/admin.rs
@@ -49,7 +49,7 @@ use ai_memory_store::{
ApproveAutoImproveProposalResult, AutoImproveProposalOperation, AutoImproveProposalStatus,
DecayParams, EmbeddingWrite, NewAutoImproveProposal, ReaderPool, RejectAutoImproveProposal,
ScopeResolutionError, StageAutoImproveRun, StoreError, WriterHandle, create_explicit_scope,
- f32_vec_to_bytes, lookup_existing_scope,
+ f32_vec_to_bytes, lookup_existing_scope, lookup_existing_workspace,
};
use ai_memory_wiki::{AdmissionContext, AdmissionOp, Markdown, Wiki, WikiError, WritePageRequest};
use axum::Json;
@@ -1028,6 +1028,16 @@ async fn lookup_ws_proj_no_create(
.map_err(scope_err)
}
+/// Look up a workspace by name **without** auto-creating it.
+async fn lookup_ws_no_create(
+ state: &AdminState,
+ workspace: &str,
+) -> Result<WorkspaceId, (StatusCode, Json<serde_json::Value>)> {
+ lookup_existing_workspace(&state.reader, workspace)
+ .await
+ .map_err(scope_err)
+}
+
fn scope_err(err: ScopeResolutionError) -> (StatusCode, Json<serde_json::Value>) {
let status = if err.is_bad_request() {
StatusCode::BAD_REQUEST
@@ -2975,6 +2985,8 @@ pub struct RenameWorkspaceResult {
/// Post-rename mirror checkpoint, if one was taken.
#[serde(skip_serializing_if = "Option::is_none")]
pub checkpoint: Option<String>,
+ /// Number of scope manifests refreshed after the SQLite rename.
+ pub manifests_refreshed: usize,
}
/// `POST /admin/rename-workspace` — rename a workspace (column-only; the
@@ -2983,22 +2995,9 @@ async fn handle_rename_workspace(
State(state): State<Arc<AdminState>>,
Json(req): Json<RenameWorkspaceRequest>,
) -> impl IntoResponse {
- let ws_id = match state.reader.find_workspace(req.from.clone()).await {
- Ok(Some(id)) => id,
- Ok(None) => {
- return (
- StatusCode::NOT_FOUND,
- Json(serde_json::json!({
- "error": format!("workspace '{}' not found", req.from)
- })),
- );
- }
- Err(e) => {
- return (
- StatusCode::INTERNAL_SERVER_ERROR,
- Json(serde_json::json!({ "error": e.to_string() })),
- );
- }
+ let ws_id = match lookup_ws_no_create(&state, &req.from).await {
+ Ok(id) => id,
+ Err(e) => return e,
};
if let Err(e) = state.writer.rename_workspace(ws_id, req.to.clone()).await {
let status = match &e {
@@ -3010,6 +3009,10 @@ async fn handle_rename_workspace(
};
return (status, Json(serde_json::json!({ "error": e.to_string() })));
}
+ let manifests_refreshed = match state.wiki.backfill_scope_manifests().await {
+ Ok(n) => n,
+ Err(e) => return internal_err(e.to_string()),
+ };
let checkpoint = checkpoint_or_warn(
&state.wiki,
format!("rename-workspace {} -> {}", req.from, req.to),
@@ -3018,6 +3021,7 @@ async fn handle_rename_workspace(
from: req.from.clone(),
to: req.to.clone(),
checkpoint,
+ manifests_refreshed,
};
(
StatusCode::OK,
@@ -3045,6 +3049,13 @@ pub struct DeleteWorkspaceResult {
pub projects_deleted: u64,
/// `pages` rows removed via cascade (all versions).
pub pages_deleted: u64,
+ /// Paths removed from disk (the workspace's UUID-namespaced directory).
+ pub files_deleted: Vec<String>,
+ /// Paths that could not be removed from disk (non-fatal; DB rows are gone).
+ pub files_failed: Vec<String>,
+ /// Pre-delete checkpoint, if the tree had uncommitted changes.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub pre_checkpoint: Option<String>,
/// Post-delete mirror checkpoint, if one was taken.
#[serde(skip_serializing_if = "Option::is_none")]
pub checkpoint: Option<String>,
@@ -3055,24 +3066,58 @@ pub struct DeleteWorkspaceResult {
/// `force` (a typo shouldn't wipe live data). Orphan-workspace cleanup.
async fn handle_delete_workspace(
State(state): State<Arc<AdminState>>,
+ actor_ext: Option<axum::Extension<ai_memory_core::ActorContext>>,
Json(req): Json<DeleteWorkspaceRequest>,
) -> impl IntoResponse {
- let ws_id = match state.reader.find_workspace(req.workspace.clone()).await {
- Ok(Some(id)) => id,
- Ok(None) => {
- return (
- StatusCode::NOT_FOUND,
- Json(serde_json::json!({
- "error": format!("workspace '{}' not found", req.workspace)
- })),
- );
- }
- Err(e) => {
- return (
- StatusCode::INTERNAL_SERVER_ERROR,
- Json(serde_json::json!({ "error": e.to_string() })),
- );
+ let ws_id = match lookup_ws_no_create(&state, &req.workspace).await {
+ Ok(id) => id,
+ Err(e) => return e,
+ };
+
+ if !req.force {
+ match state
+ .reader
+ .list_projects_with_stats_for_workspace(req.workspace.clone())
+ .await
+ {
+ Ok(projects) if !projects.is_empty() => {
+ return (
+ StatusCode::CONFLICT,
+ Json(serde_json::json!({
+ "error": StoreError::WorkspaceNotEmpty(projects.len() as u64).to_string()
+ })),
+ );
+ }
+ Ok(_) => {}
+ Err(e) => return internal_err(e.to_string()),
}
+ }
+
+ let actor = actor_ext
+ .map(|axum::Extension(a)| a)
+ .unwrap_or_else(ai_memory_core::ActorContext::anonymous);
+ let purge_ctx = AdmissionContext {
+ workspace: req.workspace.clone(),
+ project: String::new(),
+ op: AdmissionOp::PurgeWorkspace,
+ actor,
+ ..Default::default()
+ };
+ let resolved_purge_ctx = match state
+ .wiki
+ .admit_purge_workspace(ws_id, Some(purge_ctx))
+ .await
+ {
+ Ok(ctx) => ctx,
+ Err(e) => return internal_err(e.to_string()),
+ };
+
+ let pre_checkpoint = match checkpoint_or_500(
+ &state.wiki,
+ format!("pre-delete-workspace {}", req.workspace),
+ ) {
+ Ok(oid) => oid,
+ Err(e) => return e,
};
let summary = match state.writer.delete_workspace(ws_id, req.force).await {
@@ -3087,16 +3132,37 @@ async fn handle_delete_workspace(
}
};
- // DB rows are gone (cascade); drop the on-disk dir best-effort so a
- // filesystem hiccup doesn't fail an already-durable delete.
- if let Err(e) = state.wiki.remove_workspace_dir(ws_id).await {
- warn!(error = %e, workspace = %req.workspace, "delete-workspace: on-disk dir removal failed");
+ let ws_root_str = state
+ .wiki
+ .root()
+ .join(ws_id.to_string())
+ .display()
+ .to_string();
+ let mut files_deleted = Vec::new();
+ let mut files_failed = Vec::new();
+ match state.wiki.remove_workspace_dir(ws_id).await {
+ Ok(()) => files_deleted.push(ws_root_str.clone()),
+ Err(e) => {
+ warn!(error = %e, workspace = %req.workspace, path = %ws_root_str, "delete-workspace: on-disk dir removal failed");
+ files_failed.push(ws_root_str);
+ }
}
+ let mut dispatch_ctx = resolved_purge_ctx;
+ if !files_failed.is_empty()
+ && let Some(ref mut c) = dispatch_ctx
+ {
+ c.partial_failure = true;
+ }
+ state.wiki.dispatch_purge_workspace(dispatch_ctx.as_ref());
+
let result = DeleteWorkspaceResult {
workspace: req.workspace.clone(),
projects_deleted: summary.projects_deleted,
pages_deleted: summary.pages_deleted,
+ files_deleted,
+ files_failed,
+ pre_checkpoint,
checkpoint: checkpoint_or_warn(&state.wiki, format!("delete-workspace {}", req.workspace)),
};
(
@@ -6422,6 +6488,16 @@ mod tests {
"confirm": true
}),
),
+ (
+ "POST",
+ "/admin/delete-workspace",
+ serde_json::json!({"workspace": "default", "force": true}),
+ ),
+ (
+ "POST",
+ "/admin/rename-workspace",
+ serde_json::json!({"from": "default", "to": "renamed"}),
+ ),
(
"POST",
"/admin/write-page",
@@ -6525,6 +6601,45 @@ mod tests {
assert_eq!(resp.status(), StatusCode::OK);
}
+ #[tokio::test]
+ async fn multiuser_workspace_admin_routes_reach_handler_for_root() {
+ let (_tmp, router) = user_admin_test_router("root-token");
+ for (uri, payload) in [
+ (
+ "/admin/delete-workspace",
+ serde_json::json!({"workspace": "missing", "force": true}),
+ ),
+ (
+ "/admin/rename-workspace",
+ serde_json::json!({"from": "missing", "to": "renamed"}),
+ ),
+ ] {
+ let resp = router
+ .clone()
+ .oneshot(
+ Request::builder()
+ .method("POST")
+ .uri(uri)
+ .header("authorization", "Bearer root-token")
+ .header("content-type", "application/json")
+ .body(Body::from(serde_json::to_vec(&payload).unwrap()))
+ .unwrap(),
+ )
+ .await
+ .unwrap();
+ assert_ne!(
+ resp.status(),
+ StatusCode::UNAUTHORIZED,
+ "{uri} rejected root auth"
+ );
+ assert_ne!(
+ resp.status(),
+ StatusCode::FORBIDDEN,
+ "{uri} rejected root auth"
+ );
+ }
+ }
+
#[tokio::test]
async fn create_user_happy_path_returns_token_once() {
let (_tmp, router) = user_admin_test_router("root-token");
diff --git a/crates/ai-memory-mcp/tests/admin_move.rs b/crates/ai-memory-mcp/tests/admin_move.rs
index f2dae19d..35e3bf0d 100644
--- a/crates/ai-memory-mcp/tests/admin_move.rs
+++ b/crates/ai-memory-mcp/tests/admin_move.rs
@@ -34,7 +34,38 @@ use tower::ServiceExt;
async fn make_state(tmp: &TempDir) -> (AdminState, Store) {
let store = Store::open(tmp.path()).unwrap();
- let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
+ let wiki = Wiki::new(tmp.path(), store.writer.clone())
+ .unwrap()
+ .with_store_reader(store.reader.clone());
+ let db_path = store.db_path().to_path_buf();
+ let state = AdminState {
+ writer: store.writer.clone(),
+ reader: store.reader.clone(),
+ wiki,
+ llm: None,
+ auto_improve_require_approval: false,
+ auto_improve_review_config: Default::default(),
+ embedder: None,
+ provider_health: ai_memory_llm::ProviderHealth::default(),
+ decay_params: DecayParams::default(),
+ data_dir: tmp.path().to_path_buf(),
+ db_path,
+ bind: "127.0.0.1:0".to_string(),
+ home_dir: None,
+ bootstrap_lock: std::sync::Arc::new(tokio::sync::Mutex::new(())),
+ token_pepper: None,
+ active_project: ai_memory_core::ActiveProject::new(),
+ on_project_moved: None,
+ };
+ (state, store)
+}
+
+async fn make_state_with_chain(tmp: &TempDir, chain: AdmissionChain) -> (AdminState, Store) {
+ let store = Store::open(tmp.path()).unwrap();
+ let wiki = Wiki::new(tmp.path(), store.writer.clone())
+ .unwrap()
+ .with_admission_chain(chain)
+ .with_store_reader(store.reader.clone());
let db_path = store.db_path().to_path_buf();
let state = AdminState {
writer: store.writer.clone(),
@@ -1803,3 +1834,178 @@ async fn rename_workspace_ok_collision_and_unknown() {
assert_eq!(resp.status(), StatusCode::NOT_FOUND);
}
}
+
+#[tokio::test]
+async fn rename_workspace_refreshes_scope_manifests() {
+ let tmp = TempDir::new().unwrap();
+ let (state, store) = make_state(&tmp).await;
+ seed_page(&store, &state.wiki, "old", "proj", "notes/a.md", "b").await;
+ state.wiki.backfill_scope_manifests().await.unwrap();
+ let ws_id = store
+ .reader
+ .find_workspace("old".into())
+ .await
+ .unwrap()
+ .expect("workspace exists");
+
+ let resp = post(
+ state,
+ "/admin/rename-workspace",
+ json!({"from":"old","to":"new"}),
+ )
+ .await;
+
+ assert_eq!(resp.status(), StatusCode::OK);
+ let body = body_json(resp).await;
+ assert!(
+ body["manifests_refreshed"].as_u64().unwrap_or(0) >= 1,
+ "rename should rewrite the workspace manifest: {body}"
+ );
+ let manifest = std::fs::read_to_string(
+ tmp.path()
+ .join("wiki")
+ .join(ws_id.to_string())
+ .join("_meta.md"),
+ )
+ .unwrap();
+ assert!(manifest.contains("workspace: new"), "{manifest}");
+ assert!(!manifest.contains("workspace: old"), "{manifest}");
+}
+
+#[tokio::test]
+async fn delete_workspace_reject_policy_aborts_before_db_or_disk_destruction() {
+ let app = Router::new().route(
+ "/hook",
+ axum_post(
+ |headers: HeaderMap, Json(_payload): Json<serde_json::Value>| async move {
+ let op = headers
+ .get("X-Memory-Op")
+ .and_then(|v| v.to_str().ok())
+ .unwrap_or("");
+ assert_eq!(op, "purge_workspace");
+ (StatusCode::INTERNAL_SERVER_ERROR, "no workspace purge")
+ },
+ ),
+ );
+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let url = format!("http://{}/hook", listener.local_addr().unwrap());
+ tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
+
+ let tmp = TempDir::new().unwrap();
+ let chain = AdmissionChain::new(vec![WebhookConfig {
+ name: "rejecting-mirror".into(),
+ url,
+ timeout_ms: 2_000,
+ failure_policy: FailurePolicy::Reject,
+ events: vec![AdmissionOp::PurgeWorkspace],
+ blocking: true,
+ }])
+ .unwrap();
+ let (state, store) = make_state_with_chain(&tmp, chain).await;
+ seed_page(&store, &state.wiki, "victim", "proj", "notes/a.md", "body").await;
+ let ws_id = store
+ .reader
+ .find_workspace("victim".into())
+ .await
+ .unwrap()
+ .expect("workspace exists");
+ let ws_root = tmp.path().join("wiki").join(ws_id.to_string());
+
+ let resp = post(
+ state,
+ "/admin/delete-workspace",
+ json!({ "workspace": "victim", "force": true }),
+ )
+ .await;
+
+ assert_eq!(resp.status(), StatusCode::INTERNAL_SERVER_ERROR);
+ assert!(
+ store
+ .reader
+ .find_workspace("victim".into())
+ .await
+ .unwrap()
+ .is_some(),
+ "rejecting admission must leave DB rows intact"
+ );
+ assert!(
+ ws_root.exists(),
+ "rejecting admission must leave disk intact"
+ );
+}
+
+#[tokio::test]
+async fn delete_workspace_reports_partial_disk_failure_and_dispatches_notification() {
+ let (tx, rx) = tokio::sync::oneshot::channel::<serde_json::Value>();
+ let tx = Arc::new(Mutex::new(Some(tx)));
+ let tx_for_route = tx.clone();
+ let app = Router::new().route(
+ "/hook",
+ axum_post(move |Json(payload): Json<serde_json::Value>| {
+ let tx_for_route = tx_for_route.clone();
+ async move {
+ if let Some(tx) = tx_for_route.lock().unwrap().take() {
+ let _ = tx.send(payload);
+ }
+ StatusCode::NO_CONTENT
+ }
+ }),
+ );
+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let url = format!("http://{}/hook", listener.local_addr().unwrap());
+ tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
+
+ let tmp = TempDir::new().unwrap();
+ let chain = AdmissionChain::new(vec![WebhookConfig {
+ name: "async-mirror".into(),
+ url,
+ timeout_ms: 2_000,
+ failure_policy: FailurePolicy::Ignore,
+ events: vec![AdmissionOp::PurgeWorkspace],
+ blocking: false,
+ }])
+ .unwrap();
+ let (state, store) = make_state_with_chain(&tmp, chain).await;
+ seed_page(&store, &state.wiki, "victim", "proj", "notes/a.md", "body").await;
+ let ws_id = store
+ .reader
+ .find_workspace("victim".into())
+ .await
+ .unwrap()
+ .expect("workspace exists");
+ let ws_root = tmp.path().join("wiki").join(ws_id.to_string());
+ std::fs::remove_dir_all(&ws_root).unwrap();
+ std::fs::write(&ws_root, "not a directory").unwrap();
+
+ let resp = post(
+ state,
+ "/admin/delete-workspace",
+ json!({ "workspace": "victim", "force": true }),
+ )
+ .await;
+
+ assert_eq!(resp.status(), StatusCode::OK);
+ let body = body_json(resp).await;
+ assert!(
+ body["files_deleted"].as_array().unwrap().is_empty(),
+ "{body}"
+ );
+ assert_eq!(body["files_failed"].as_array().unwrap().len(), 1, "{body}");
+ assert!(
+ store
+ .reader
+ .find_workspace("victim".into())
+ .await
+ .unwrap()
+ .is_none(),
+ "DB delete should still commit and be reported as partial filesystem failure"
+ );
+
+ let payload = tokio::time::timeout(std::time::Duration::from_secs(2), rx)
+ .await
+ .expect("async purge_workspace dispatch should fire")
+ .unwrap();
+ assert_eq!(payload["ctx"]["op"], "purge_workspace");
+ assert_eq!(payload["ctx"]["workspace"], "victim");
+ assert_eq!(payload["ctx"]["partial_failure"], true);
+}
diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rs
index e27fd79d..16903f9a 100644
--- a/crates/ai-memory-store/src/lib.rs
+++ b/crates/ai-memory-store/src/lib.rs
@@ -46,8 +46,8 @@ pub use reader::{
};
pub use scope::{
ResolvedScope, ScopeName, ScopeResolutionError, ScopeResolver, WORKSPACE_PROJECT_PAIR_REQUIRED,
- create_explicit_scope, create_global_scope, lookup_existing_scope, lookup_global_scope,
- resolve_many_existing_scopes,
+ create_explicit_scope, create_global_scope, lookup_existing_scope, lookup_existing_workspace,
+ lookup_global_scope, resolve_many_existing_scopes,
};
pub use users::{TOKEN_HASH_LEN, TOKEN_RAW_LEN, TokenPepper, generate_token, hash_token};
pub use writer::WriterHandle;
diff --git a/crates/ai-memory-store/src/scope.rs b/crates/ai-memory-store/src/scope.rs
index 5f79b822..969c4376 100644
--- a/crates/ai-memory-store/src/scope.rs
+++ b/crates/ai-memory-store/src/scope.rs
@@ -183,12 +183,7 @@ pub async fn lookup_existing_scope(
workspace: &str,
project: &str,
) -> Result<ResolvedScope, ScopeResolutionError> {
- let workspace_id = reader
- .find_workspace(workspace.to_owned())
- .await?
- .ok_or_else(|| ScopeResolutionError::WorkspaceNotFound {
- workspace: workspace.to_owned(),
- })?;
+ let workspace_id = lookup_existing_workspace(reader, workspace).await?;
let project_id = reader
.find_project(workspace_id, project.to_owned())
.await?
@@ -202,6 +197,22 @@ pub async fn lookup_existing_scope(
})
}
+/// Look up an explicit workspace by name without creating anything.
+///
+/// This is for admin/destructive surfaces that operate at workspace granularity
+/// and must fail closed on typos instead of auto-creating a scope.
+pub async fn lookup_existing_workspace(
+ reader: &ReaderPool,
+ workspace: &str,
+) -> Result<WorkspaceId, ScopeResolutionError> {
+ reader
+ .find_workspace(workspace.to_owned())
+ .await?
+ .ok_or_else(|| ScopeResolutionError::WorkspaceNotFound {
+ workspace: workspace.to_owned(),
+ })
+}
+
/// Create or fetch an explicit workspace/project pair.
///
/// This is the only helper that may create a scope, and should only be used by
diff --git a/crates/ai-memory-wiki/src/admission.rs b/crates/ai-memory-wiki/src/admission.rs
index 997729ef..05dad75c 100644
--- a/crates/ai-memory-wiki/src/admission.rs
+++ b/crates/ai-memory-wiki/src/admission.rs
@@ -56,6 +56,9 @@ pub enum AdmissionOp {
/// `remove_dir_all`). Carries the project (ctx), no page path. Lets a
/// mirror remove the project's directory.
PurgeProject,
+ /// A whole workspace is being purged. Carries the workspace (ctx), no page
+ /// path, and an empty project. Lets a mirror remove the workspace tree.
+ PurgeWorkspace,
/// A whole project is being moved between workspaces without changing its
/// project id. Carries source names in `workspace`/`project` and
/// destination names in `destination_workspace`/`destination_project`.
@@ -71,6 +74,7 @@ impl AdmissionOp {
AdmissionOp::Consolidate => "consolidate",
AdmissionOp::Delete => "delete",
AdmissionOp::PurgeProject => "purge_project",
+ AdmissionOp::PurgeWorkspace => "purge_workspace",
AdmissionOp::MoveProject => "move_project",
}
}
@@ -570,6 +574,25 @@ mod tests {
assert!(matches!(op, AdmissionOp::WritePage));
}
+ #[test]
+ fn purge_workspace_header_value_is_stable() {
+ assert_eq!(
+ AdmissionOp::PurgeWorkspace.as_header_value(),
+ "purge_workspace"
+ );
+ }
+
+ #[test]
+ fn purge_workspace_event_deserializes_from_config_value() {
+ let cfg: WebhookConfig = serde_json::from_value(serde_json::json!({
+ "name": "mirror",
+ "url": "http://127.0.0.1:1/hook",
+ "events": ["purge_workspace"]
+ }))
+ .unwrap();
+ assert_eq!(cfg.events, vec![AdmissionOp::PurgeWorkspace]);
+ }
+
#[test]
fn webhook_timeout_is_clamped_to_smart_bounds() {
assert_eq!(webhook_timeout(0), Duration::from_millis(1));
diff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rs
index 9620ad43..4a16458b 100644
--- a/crates/ai-memory-wiki/src/wiki.rs
+++ b/crates/ai-memory-wiki/src/wiki.rs
@@ -436,6 +436,17 @@ impl Wiki {
}
}
+ /// Best-effort fill of `ctx.workspace` from a workspace id via the store
+ /// reader. Workspace-wide ops have no project id to resolve.
+ async fn resolve_workspace_name(&self, workspace_id: WorkspaceId, ctx: &mut AdmissionContext) {
+ if let Some(reader) = &self.store_reader
+ && ctx.workspace.is_empty()
+ && let Ok(Some(name)) = reader.workspace_name_by_id(workspace_id).await
+ {
+ ctx.workspace = name;
+ }
+ }
+
/// Delete a single page file. When an admission chain is attached, it is
/// notified (`op=delete`) BEFORE the file is removed, so a mirror can
/// `git rm` the same path. A `Reject`-policy webhook aborts the delete.
@@ -543,6 +554,29 @@ impl Wiki {
}
}
+ /// Run the blocking admission notification for a workspace purge without
+ /// removing files. Admin callers use this before the DB purge so a
+ /// `failure_policy = reject` webhook can still abort all destructive work.
+ ///
+ /// # Errors
+ /// Returns [`WikiError`] when a reject-policy webhook fails.
+ pub async fn admit_purge_workspace(
+ &self,
+ workspace_id: WorkspaceId,
+ admission_ctx: Option<AdmissionContext>,
+ ) -> WikiResult<Option<AdmissionContext>> {
+ if let Some(chain) = &self.admission_chain {
+ let mut ctx = admission_ctx.unwrap_or_default();
+ ctx.op = AdmissionOp::PurgeWorkspace;
+ self.resolve_workspace_name(workspace_id, &mut ctx).await;
+ ctx.project.clear();
+ chain.notify(None, &ctx).await?;
+ Ok(Some(ctx))
+ } else {
+ Ok(None)
+ }
+ }
+
/// Remove the project's on-disk directory without running admission.
///
/// # Errors
@@ -585,6 +619,14 @@ impl Wiki {
}
}
+ /// Dispatch non-blocking purge-workspace webhooks after the caller's purge
+ /// has completed its durable DB/filesystem work.
+ pub fn dispatch_purge_workspace(&self, admission_ctx: Option<&AdmissionContext>) {
+ if let (Some(chain), Some(ctx)) = (&self.admission_chain, admission_ctx) {
+ chain.dispatch_async(None, &serde_json::Value::Null, "", ctx);
+ }
+ }
+
/// Cloneable handle to the underlying store writer.
#[must_use]
pub fn writer(&self) -> &WriterHandle {
diff --git a/docs/admission-webhooks.md b/docs/admission-webhooks.md
index c523710f..5ba73ed8 100644
--- a/docs/admission-webhooks.md
+++ b/docs/admission-webhooks.md
@@ -1,7 +1,7 @@
# Admission webhooks: pre-persistence HTTP hooks
> Operator-configured HTTP hooks invoked on the engine's write path
-> (`Wiki::write_page`, `delete_page`, `purge_project`, `move_project`)
+> (`Wiki::write_page`, `delete_page`, `purge_project`, `purge_workspace`, `move_project`)
> just before the durable mutation commits. Write hooks can mutate the page
> (return a new frontmatter / body); delete/purge/move hooks are notifications
> that can observe, mirror, or reject. Sourced from
@@ -50,6 +50,11 @@ Webhooks fire on these `op` values today (extensible enum):
`remove_dir_all`, routed from `/admin/purge-project`). Carries the
project in `ctx`, **no** page path; fired before the directory is
removed so a mirror can drop the project.
+- `purge_workspace` — a whole workspace is purged (routed from
+ `/admin/delete-workspace`). Carries the workspace in `ctx.workspace`, leaves
+ `ctx.project` empty, and has **no** page path; fired before SQL/file
+ destruction for reject-policy admission and dispatched again to non-blocking
+ observers after durable work.
- `move_project` — a whole project is moved between workspaces without
changing `project_id` (fresh-destination true move). Carries the source
project in `ctx.workspace` / `ctx.project`, destination names in
@@ -57,12 +62,13 @@ Webhooks fire on these `op` values today (extensible enum):
fired before the directory rename + DB re-stamp so a mirror can rename or
reject the project move.
-`delete` / `purge_project` / `move_project` are notifications — there is no
+`delete` / `purge_project` / `purge_workspace` / `move_project` are notifications — there is no
body to mutate; a `Reject`-policy webhook still aborts the operation
(admission fires BEFORE the SQL destruction in both the `/admin/purge-project`
-and `/admin/move-project` copy-purge paths, so reject leaves the source
-intact). Each webhook opts into the ops it cares about via `events`; the
-chain checks the op against `WebhookConfig::events` before dispatching.
+and `/admin/delete-workspace` paths, and before source teardown in
+`/admin/move-project` copy-purge paths, so reject leaves the source intact).
+Each webhook opts into the ops it cares about via `events`; the chain checks the
+op against `WebhookConfig::events` before dispatching.
A copy-purge `/admin/move-project` fires **two** webhook events from
one request: one or more `write_page` notifications as the pages copy
@@ -71,6 +77,10 @@ when the source is torn down. The `purge_project` event carries
`partial_failure: true` if the SQL purge committed but the on-disk
dir removal failed afterwards.
+`/admin/delete-workspace` emits `purge_workspace`. Its final async observer
+notification carries `partial_failure: true` if the SQL workspace cascade
+committed but `<wiki_root>/<workspace_id>` could not be removed.
+
During the copy leg, the engine skips only the webhook named exactly
`contributors`. Move copies preserve page frontmatter verbatim, including any
existing `contributors` list, so re-running that enrichment hook for every page
@@ -91,6 +101,9 @@ terminal `purge_project` notification is unchanged.
do. (Only `purge_project` removes files in bulk.)
- **`rename-project`** — a `projects.name` column update; the on-disk path
is the stable UUID, so no file moves and nothing to propagate.
+- **`rename-workspace`** — a `workspaces.name` column update plus refreshed
+ `_meta.md` manifests; workspace paths are stable UUIDs, so no file move
+ notification is needed.
- **External / manual edits on disk** — reconciled by the watcher, not the
admission chain (the chain is for the engine's own write path).
@@ -101,7 +114,7 @@ terminal `purge_project` notification is unchanged.
```http
POST <webhook.url>
Content-Type: application/json
-X-Memory-Op: write_page | consolidate | delete | purge_project | move_project
+X-Memory-Op: write_page | consolidate | delete | purge_project | purge_workspace | move_project
```
```jsonc
@@ -123,8 +136,8 @@ X-Memory-Op: write_page | consolidate | delete | purge_project | move_project
"client": "72836f52-...", // DCR client UUID
"session_id": "019e6d-..."
},
- "op": "write_page", // write_page | consolidate | delete | purge_project | move_project
- "partial_failure": true // purge_project only, and ONLY when set
+ "op": "write_page", // write_page | consolidate | delete | purge_project | purge_workspace | move_project
+ "partial_failure": true // purge_project/purge_workspace only, and ONLY when set
// (skipped on the wire when false).
// true → the DB rows were purged but
// `remove_project_dir` failed afterwards;
diff --git a/docs/lifecycle-ops.md b/docs/lifecycle-ops.md
index 054ab409..9e912276 100644
--- a/docs/lifecycle-ops.md
+++ b/docs/lifecycle-ops.md
@@ -10,6 +10,8 @@ on a homelab box where mistakes are harder to undo.
|---|---|---|---|---|
| `purge-project --confirm` | ✅ yes | the one project's data | no | Atomic `rm -rf <project_root>` on the namespaced disk path; sibling projects untouched. |
| `rename-project --from --to` | ✅ yes | no | yes (rename back) | Column-only update on `projects.name`. The on-disk dir is keyed by `project_id` (UUID), so the rename never moves a file. |
+| `/admin/rename-workspace` | ✅ yes | no | yes (rename back) | Column-only update on `workspaces.name`; refreshes `_meta.md` scope manifests and checkpoints the wiki tree. |
+| `/admin/delete-workspace` | ✅ yes | the workspace and every child project | no | Runs `purge_workspace` admission first, deletes SQLite rows in one cascade, removes the UUID-keyed workspace directory, reports filesystem partial failures, and dispatches mirror notification after durable work. |
| `move-project --confirm` | ✅ yes | source only in the merge case (a `Reject`-policy `purge_project` webhook can still abort the source teardown leaving everything intact) | no | Fresh destination → lossless **true move** (re-stamp `workspace_id`, keep `project_id`, rename the dir): sessions/observations/handoffs + history all survive. Destination with a same-named project → **copy+purge merge**: only latest pages migrate. |
| `backup --output-path` | ✅ yes | no | n/a | Streams a gzipped tarball from the server's online `sqlite3 .backup` plus the wiki tree. Safe alongside the live writer. |
| `checkpoints` | ✅ yes | no | n/a | Lists recent wiki git checkpoints. Read-only. |
@@ -130,6 +132,46 @@ Failure modes:
- **`to` invalid (empty, slash, whitespace)** → 422.
- **Source `from` not found** → 404.
+### `/admin/rename-workspace`
+
+Renames a workspace by updating `workspaces.name`; on-disk paths remain keyed by
+`workspace_id`, so no page files move. After the SQLite rename, the handler
+refreshes `_meta.md` scope manifests with `Wiki::backfill_scope_manifests()` and
+returns `manifests_refreshed` plus a post-rename checkpoint when the wiki tree
+changed.
+
+Failure modes:
+
+- **Source `from` not found** → 404.
+- **`to` name already exists or is invalid** → 422.
+
+### `/admin/delete-workspace`
+
+Deletes a workspace row and all child projects/pages/sessions through the
+`workspace_id` cascade. The route is guarded by `force: true` for non-empty
+workspaces and follows the destructive-operation ordering used by project
+purges:
+
+1. Look up the workspace without creating missing scopes.
+2. Run blocking `op=purge_workspace` admission. A reject-policy webhook aborts
+ before DB rows or files are removed.
+3. Take a pre-delete checkpoint if the wiki tree is dirty.
+4. Delete the workspace in one writer-actor transaction.
+5. Remove `<wiki_root>/<workspace_id>` from disk.
+6. Dispatch non-blocking `purge_workspace` mirror notifications after durable
+ work. If the DB delete committed but disk removal failed, the response
+ includes `files_failed` and webhook `ctx.partial_failure: true`.
+7. Take a post-delete checkpoint if the wiki tree changed.
+
+Failure modes:
+
+- **Workspace not found** → 404, no mutation.
+- **Non-empty workspace without `force: true`** → 409, no mutation.
+- **Reject-policy `purge_workspace` webhook fails** → 500, no DB/disk mutation.
+- **Filesystem removal fails after SQL commit** → 200 with `files_failed`
+ populated and `partial_failure: true` on async mirror notifications; manual
+ cleanup of the reported path is required.
+
### `move-project`
```bash