Skip to content

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

Rust
641 KB
Raw Blame
//! Admin HTTP routes — state-touching operations invoked by the CLI
//! over plain HTTP (not MCP). Currently exposes:
//!
//! - `POST /admin/backup`         — snapshot db + wiki into a gzip tarball (binary response).
//! - `POST /admin/bootstrap`      — ingest a pre-collected source bundle
//!   into seed wiki pages via the configured LLM provider.
//! - `POST /admin/auto-improve`   — review one session and apply or stage proposals.
//! - `POST /admin/auto-improve/report` — read-only auto-improve telemetry report.
//! - `POST /admin/curator`        — dry-run or stage a rule-based curator report.
//! - `GET  /admin/status`         — lifetime counts + server data-dir info.
//! - `GET  /admin/metrics`        — content-free Prometheus counters and latency histograms.
//! - `GET  /admin/projects`       — authoritative `(workspace, project)` list.
//! - `GET  /admin/project-coordinate` — read-only exact/compatibility diagnosis.
//! - `GET  /admin/open-sessions`  — open (not yet ended) sessions for one scope + agent
//!   (an exact `session_id` plus `include_ended=true` also matches an ended one).
//! - `GET  /admin/sessions/by-agent` — session counts per agent CLI for one scope.
//! - `GET  /admin/activity/by-client` — MCP tool-call counts per client (server-wide).
//! - `GET  /admin/audit-log`      — paginated read of the append-only `audit_log`.
//! - `GET  /admin/search?q=`      — FTS5 hits against the wiki index.
//! - `GET  /admin/recent`         — most recently updated wiki pages.
//! - `POST /admin/reorg`          — retro-fit sessions to per-cwd projects.
//! - `POST /admin/lint`           — run the M8 lint pass.
//! - `POST /admin/forget-sweep`   — run the M8 retention sweep.
//! - `POST /admin/embed`          — backfill embeddings for latest pages.
//! - `POST /admin/commit`         — stage + commit the wiki tree via git.
//! - `GET  /admin/checkpoints`    — list recent wiki git checkpoints.
//! - `POST /admin/restore-page`   — restore one page from retained history.
//! - `POST /admin/purge-project`  — delete a project's rows and wiki files
//!   (logical unless `compact` is set; see `ai_memory_store::Compaction`).
//! - `POST /admin/purge-session`  — delete one session and what it derived.
//! - `POST /admin/repair-session-times` — correct `started_at`/`ended_at` of
//!   already-imported sessions from caller-supplied candidate times (the CLI
//!   computes them from local transcripts; see `ai-memory
//!   repair-backfill-timestamps`).
//! - `POST /admin/rename-project` — rename a project (column-only; no files move).
//! - `POST /admin/rename-workspace` — rename a workspace and refresh scope manifests.
//! - `POST /admin/compact`        — reclaim free pages; deletes nothing.
//! - `POST /admin/reclaim-ledger-versions` — drop the superseded ledger
//!   versions the pre-#660 indexer left behind, and nothing else.
//! - `POST /admin/delete-workspace` — delete a workspace and its projects
//!   (logical unless `compact` is set; see `ai_memory_store::Compaction`).
//! - `POST /admin/merge-workspace` — fold every project of one workspace into
//!   another, then delete the emptied source workspace.
//! - `POST /admin/move-project`   — move a project into another workspace
//! - `POST /admin/merge-project`  — losslessly join two projects in one workspace
//!   (copy latest pages via the write path, then purge the source).
//! - `POST /admin/write-page`     — write or update a wiki page atomically.
//! - `GET  /admin/read-page`      — fetch the full body of a single wiki page by path.
//! - `POST /admin/delete-page`    — delete a single wiki page by path.
//!
//! The CLI is responsible for filesystem access (collecting sources from
//! the project repo, rendering output for humans); the server is
//! responsible for all state reads/writes against the wiki + SQLite.

use std::sync::Arc;

use std::future::Future;
use std::io::Seek;
use std::path::PathBuf;
use std::pin::Pin;

use ai_memory_consolidate::{
    AutoImproveReviewConfig, AutoImproveTelemetryParams, AutoImproveTelemetryReport, Bootstrap,
    BootstrapConfig, BootstrapOutcome, BootstrapSource, ColdClusterDedup, CuratorParams,
    CuratorReport, EmbedBackfillCounts, EmbedBackfillOptions, LedgerRetention,
    ObservationRetention, SourceCounts, prune_sources_to_budget,
    render_auto_improve_telemetry_report_markdown, render_curator_report_markdown,
    run_auto_improve_review, run_auto_improve_telemetry_report, run_curator_report_with_breadth,
    run_embedding_backfill, run_lint, run_sweep_with_ledgers,
};
use ai_memory_core::{
    ActiveProject, AgentKind, AutoImproveProposalId, Capability, DEFAULT_PROJECT_NAME,
    DEFAULT_WORKSPACE_NAME, PageId, PagePath, ProjectId, SessionId, Tier, WorkspaceId,
};
use ai_memory_llm::{
    ChatRequest, Embedder, LlmProvider, ProviderHealth, ProviderHealthSnapshot,
    error_status_and_message,
};
use ai_memory_store::{
    ApproveAutoImproveProposalResult, AuditLogFilter, AutoImproveProposalOperation,
    AutoImproveProposalStatus, DecayParams, NewAutoImproveProposal, PagesMode, ReaderPool,
    RejectAutoImproveProposal, ScopeResolutionError, SkippedProposal, StageAutoImproveRun,
    StoreError, WriterHandle, f32_vec_to_bytes, lookup_existing_scope, lookup_existing_workspace,
};
use ai_memory_wiki::{
    AdmissionContext, AdmissionOp, Markdown, MergeProjectFile, SessionPageFile, Wiki, WikiError,
    WritePageRequest,
};
use axum::Json;
use axum::Router;
use axum::body::Body;
use axum::extract::{Query, State};
use axum::http::{HeaderMap, StatusCode, header};
use axum::middleware::Next;
use axum::response::{IntoResponse, Response};
use axum::routing::{get, patch, post};
use flate2::Compression;
use flate2::write::GzEncoder;
use serde::{Deserialize, Serialize};
use tokio_util::io::ReaderStream;
use tracing::{info, warn};

const CONTRIBUTORS_WEBHOOK_NAME: &str = "contributors";

/// Sweep knobs that live beside `DecayParams` rather than inside it, injected
/// as one Extension so adding the next one is not a third router constructor.
#[derive(Clone, Copy, Default)]
struct SweepTuning {
    breadth_weight: f64,
    retention: ObservationRetention,
    /// Opt-in age bound for the hook event ledgers (disabled by default).
    ledger_retention: LedgerRetention,
    /// A2 opt-in: compact cold episodic pages instead of evicting them.
    compact_cold_episodic: bool,
}

/// Shared state for the admin router.
#[derive(Clone)]
pub struct AdminState {
    /// Writer actor handle — used to get-or-create workspace/project.
    pub writer: WriterHandle,
    /// Reader pool — used by the idempotency check inside Bootstrap.
    pub reader: ReaderPool,
    /// Wiki handle — pages are written here.
    pub wiki: Wiki,
    /// Optional LLM provider. When `None`, bootstrap returns 503.
    pub llm: Option<Arc<dyn LlmProvider>>,
    /// If true, auto-improve leaves staged proposals pending for manual
    /// approval; otherwise it approves them immediately through the normal wiki
    /// write path.
    pub auto_improve_require_approval: bool,
    /// Server-configured defaults used by direct admin auto-improvement.
    /// Request fields remain explicit overrides; omitted eval settings inherit
    /// this operator policy instead of disabling eval silently.
    pub auto_improve_review_config: AutoImproveReviewConfig,
    /// Optional embedder. When `None`, `/admin/embed` returns 503.
    pub embedder: Option<Arc<dyn Embedder>>,
    /// Passive process-scoped health recorder for configured providers.
    pub provider_health: ProviderHealth,
    /// Shared hook-ingestion counters, written by the hook path and read
    /// here for status reporting.
    pub ingest_metrics: std::sync::Arc<ai_memory_core::IngestMetrics>,
    /// The MCP server's own counters ([`crate::AiMemoryServer::mcp_metrics`]),
    /// read by `GET /admin/metrics`. A fresh instance reports zeros.
    pub mcp_metrics: std::sync::Arc<crate::McpMetrics>,
    /// Retention-decay parameters forwarded from server config.
    pub decay_params: DecayParams,
    /// Lower edge of `memory_lint`'s A5 zero-LLM contradiction-similarity
    /// band, forwarded from `config.contradiction_band_min`. Defaults to
    /// [`ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW`].
    pub contradiction_band_min: f32,
    /// Upper edge of the A5 band — see `contradiction_band_min`. Defaults to
    /// [`ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH`].
    pub contradiction_band_max: f32,
    /// Server's resolved data directory (e.g. `/data` in the docker
    /// image). Surfaced via `/admin/status` so the CLI can report
    /// "where the wiki + db actually live".
    pub data_dir: PathBuf,
    /// Resolved SQLite path inside `data_dir`. Same purpose as above.
    pub db_path: PathBuf,
    /// Server's bind address — informational, surfaced in /admin/status.
    pub bind: String,
    /// Server home directory resolved once at config load. Used to keep admin
    /// audits consistent with the hook router's cwd-prefix guard.
    pub home_dir: Option<String>,
    /// Serialises concurrent bootstrap requests. Bootstrap fans out
    /// into an LLM call + a multi-page wiki write + a git commit;
    /// running two in parallel would race the `commit_all` git ops and
    /// stack LLM cost unnecessarily. The mutex is held for the entire
    /// handler so a second caller waits its turn (request stays open
    /// until the lock is acquired, then proceeds normally).
    pub bootstrap_lock: Arc<tokio::sync::Mutex<()>>,
    /// Per-server token pepper, used by `/admin/api-credentials` to hash
    /// freshly-issued `aim_` secrets before they land in
    /// `api_credentials.token_hash`. `None` when the operator hasn't set
    /// `[auth].token_pepper` in config (single-user installs that predate
    /// v0.8); native API-credential endpoints then return 503
    /// `multi-user not enabled`.
    pub token_pepper: Option<ai_memory_store::TokenPepper>,
    /// Shared in-process pointer to the project the agent is currently
    /// active in (published by the hook router). Read by `move-project` to
    /// refuse moving the live project (unless `force`) and to keep the
    /// pointer correct after a move. Empty `ActiveProject::new()` when no
    /// hook router is attached (admin-only tests).
    pub active_project: ActiveProject,
    /// Optional hook to PROACTIVELY evict the hook router's per-cwd
    /// `(workspace_id, project_id)` cache after admin scope mutations. Admin
    /// handlers await this after successful moves/purges/deletes/renames so
    /// the next hook event re-resolves cleanly instead of racing through a
    /// stale cached pair. `None` when no hook router is attached (stdio /
    /// admin-only tests).
    pub scope_invalidator: Option<ScopeInvalidator>,
    /// True when a trusted authenticating proxy is configured to assert
    /// end-user identities (`[auth].actor_proxy_bearer_token`).
    ///
    /// Proxy-asserted operators never get a `users` row, so `users_exist()`
    /// alone answers "does this deployment distinguish operators" with a
    /// permanent no — and every proxied caller walks through the
    /// single-operator escape hatch on the `/admin/*` gate. Static config, set
    /// once at startup; `false` for every deployment that never configures a
    /// proxy secret, which is what keeps single-operator servers on their
    /// historical behaviour.
    pub trusted_proxy_identity: bool,
}

/// Async hook-router project-cache invalidator installed by the serve command.
pub type ScopeInvalidator = Arc<
    dyn Fn(ScopeInvalidation) -> Pin<Box<dyn Future<Output = ()> + Send + 'static>> + Send + Sync,
>;

/// Hook-router project-cache invalidation target for admin scope mutations.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ScopeInvalidation {
    /// Evict cache entries whose resolved project id matches.
    Project(ProjectId),
    /// Evict cache entries whose resolved workspace id matches.
    Workspace(WorkspaceId),
}

async fn invalidate_scope_cache(state: &AdminState, target: ScopeInvalidation) {
    if let Some(evict) = &state.scope_invalidator {
        evict(target).await;
    }
}

/// JSON request body for `POST /admin/bootstrap`.
#[derive(Deserialize)]
struct BootstrapRequest {
    /// Workspace name (auto-created if it doesn't exist).
    workspace: String,
    /// Project name (auto-created if it doesn't exist).
    project: String,
    /// Sources pre-collected on the client side.
    sources: Vec<BootstrapSource>,
    /// Original collection size before client-side prune (if any).
    #[serde(default)]
    sources_collected: Option<usize>,
    /// Maximum input tokens for LLM call.
    #[serde(default = "default_max_input_tokens")]
    max_input_tokens: usize,
    /// Per-LLM-call input cap; larger bundles are split into chunks.
    #[serde(default = "default_chunk_input_tokens")]
    chunk_input_tokens: usize,
    /// Skip the LLM call and page writes — returns a dry-run outcome.
    #[serde(default)]
    dry_run: bool,
    /// Allow re-bootstrap when `wiki/bootstrap.md` already exists.
    #[serde(default)]
    force: bool,
    /// Resume an interrupted bootstrap: reuse the chunks already completed
    /// for the same sources instead of re-running them (#621).
    #[serde(default)]
    resume: bool,
}

fn default_max_input_tokens() -> usize {
    50_000
}

fn default_chunk_input_tokens() -> usize {
    ai_memory_consolidate::DEFAULT_CHUNK_INPUT_TOKENS
}

/// JSON request body for `POST /admin/auto-improve`.
#[derive(Deserialize)]
struct AutoImproveRequest {
    /// Workspace name (must already exist).
    #[serde(default = "default_workspace")]
    workspace: String,
    /// Project name (must already exist).
    #[serde(default = "default_project")]
    project: String,
    /// Completed session to review.
    session_id: SessionId,
    /// Minimum observations before the LLM review runs.
    #[serde(default = "default_auto_improve_min_observations")]
    min_observations: usize,
    /// Minimum session span before the LLM review runs.
    #[serde(default = "default_auto_improve_min_session_duration_secs")]
    min_session_duration_secs: u64,
    /// Minimum proposal confidence accepted by validation.
    #[serde(default = "default_auto_improve_min_confidence")]
    min_confidence: f32,
    /// Approximate chars/4 prompt budget.
    #[serde(default = "default_auto_improve_max_input_tokens")]
    max_input_tokens: usize,
    /// Maximum validated proposals returned.
    #[serde(default = "default_auto_improve_max_proposals")]
    max_proposals_per_run: usize,
    /// Whether future raw fallback details may be considered.
    #[serde(default)]
    include_raw_fallback: bool,
    /// Maximum existing _rules/ and procedures/ pages included for patch proposals.
    #[serde(default = "default_auto_improve_max_patchable_pages")]
    max_patchable_pages: usize,
    /// Maximum body chars rendered per patchable target page.
    #[serde(default = "default_auto_improve_max_patchable_body_chars")]
    max_patchable_body_chars: usize,
    /// Maximum patch edits per proposal.
    #[serde(default = "default_auto_improve_max_edits_per_proposal")]
    max_edits_per_proposal: usize,
    /// Maximum content chars in one patch edit.
    #[serde(default = "default_auto_improve_max_edit_content_chars")]
    max_edit_content_chars: usize,
    /// Maximum aggregate changed chars in one patch proposal.
    #[serde(default = "default_auto_improve_max_changed_chars_per_proposal")]
    max_changed_chars_per_proposal: usize,
    /// Maximum patch edits accepted across one review run.
    #[serde(default = "default_auto_improve_max_patch_edits_per_run")]
    max_patch_edits_per_run: usize,
    /// Maximum recent rejection-buffer entries rendered into prompt context.
    #[serde(default = "default_auto_improve_max_rejection_context")]
    max_rejection_context: usize,
    /// Maximum age in days for rejection-buffer prompt context.
    #[serde(default = "default_auto_improve_rejection_context_days")]
    rejection_context_days: u32,
    /// Maximum materialized final body size.
    #[serde(default = "default_auto_improve_max_final_body_chars")]
    max_final_body_chars: usize,
    /// Maximum approximate tokens allowed in one _rules/ page.
    #[serde(default = "default_auto_improve_max_rule_page_tokens")]
    max_rule_page_tokens: usize,
    /// Maximum approximate tokens allowed in one procedures/ page.
    #[serde(default = "default_auto_improve_max_procedure_page_tokens")]
    max_procedure_page_tokens: usize,
    /// Synthetic actor used for staged proposal provenance.
    #[serde(default = "default_auto_improve_proposal_actor")]
    proposal_actor: String,
    /// Pending proposal sidecar folder.
    #[serde(default = "default_auto_improve_pending_path")]
    pending_path: String,
    /// Removed compatibility field. Executable eval policy is server-owned;
    /// requests that still send this field fail closed.
    #[serde(default)]
    eval: Option<serde_json::Value>,
    /// Removed compatibility field. Requests that still send it fail closed so
    /// old preview callers cannot accidentally write pages.
    #[serde(default)]
    dry_run: Option<bool>,
    /// Removed compatibility field.
    #[serde(default)]
    stage: Option<bool>,
    /// Removed compatibility field.
    #[serde(default)]
    mode: Option<String>,
}

#[derive(Debug, Serialize)]
struct AutoImproveStageResponse {
    run_id: String,
    approval_required: bool,
    approval_policy: String,
    session_id: String,
    summary: String,
    warnings: Vec<String>,
    rejected_candidates_count: usize,
    proposals: Vec<AutoImproveProposalOutcome>,
    /// Proposals the reviewer produced but the store did not stage, with the
    /// reason. Always present (empty on a clean run) so a consumer can tell
    /// "nothing was dropped" from "this build does not report drops".
    skipped: Vec<SkippedProposal>,
}

#[derive(Debug, Serialize)]
struct AutoImproveProposalOutcome {
    id: String,
    sidecar_path: String,
    status: String,
    page_id: Option<String>,
}

/// JSON request body for `POST /admin/auto-improve/report`.
#[derive(Deserialize)]
struct AutoImproveTelemetryReportRequest {
    /// Workspace name (must already exist).
    #[serde(default = "default_workspace")]
    workspace: String,
    /// Project name (must already exist).
    #[serde(default = "default_project")]
    project: String,
    /// Lookback window in days.
    #[serde(default = "default_auto_improve_telemetry_since_days")]
    since_days: u32,
    /// Maximum rows in each top-N count table.
    #[serde(default = "default_auto_improve_telemetry_top_limit")]
    limit: usize,
    /// Stage one pending telemetry report page instead of returning a read-only report.
    #[serde(default)]
    stage: bool,
}

#[derive(Debug, Serialize)]
struct AutoImproveTelemetryReportStageResponse {
    run_id: String,
    proposal_ids: Vec<String>,
    sidecar_paths: Vec<String>,
    /// Same reason as [`AutoImproveStageResponse::skipped`]: a single-proposal
    /// run that collides otherwise returns an empty `proposal_ids` and no clue.
    skipped: Vec<SkippedProposal>,
    report: AutoImproveTelemetryReport,
}

/// JSON request body for `POST /admin/curator`.
#[derive(Deserialize)]
struct CuratorRequest {
    /// Workspace name (must already exist).
    #[serde(default = "default_workspace")]
    workspace: String,
    /// Project name (must already exist).
    #[serde(default = "default_project")]
    project: String,
    /// Return a report without staging anything.
    #[serde(default)]
    dry_run: bool,
    /// Stage one pending report page.
    #[serde(default)]
    stage: bool,
    /// Optional mode alias (`dry_run` or `stage`).
    #[serde(default)]
    mode: Option<String>,
}

#[derive(Debug, Serialize)]
struct CuratorStageResponse {
    run_id: String,
    proposal_ids: Vec<String>,
    sidecar_paths: Vec<String>,
    /// Same reason as [`AutoImproveStageResponse::skipped`]: a single-proposal
    /// run that collides otherwise returns an empty `proposal_ids` and no clue.
    skipped: Vec<SkippedProposal>,
    report: CuratorReport,
}

/// Query for `GET /admin/handoffs` (#513).
#[derive(Debug, Deserialize)]
struct OpenHandoffsQuery {
    workspace: String,
    project: String,
    #[serde(default = "default_open_handoffs_limit")]
    limit: usize,
}

const fn default_open_handoffs_limit() -> usize {
    50
}

/// Query for `GET /admin/messages` (cross-project agent messaging, V64).
#[derive(Debug, Deserialize)]
struct ListMessagesQuery {
    workspace: String,
    project: String,
    #[serde(rename = "box", default = "default_message_box")]
    mailbox: String,
    #[serde(default = "default_list_messages_limit")]
    limit: usize,
}

fn default_message_box() -> String {
    "inbox".into()
}

const fn default_list_messages_limit() -> usize {
    50
}

/// Body cap for `POST /admin/messages/send` (V64). The body crosses a
/// project-isolation boundary and is untrusted input on the receiving side;
/// capped the same way handoff text fields are, after secret-scrubbing.
const MESSAGE_BODY_MAX_CHARS: usize = 8000;

/// Subject cap for `POST /admin/messages/send` (V64).
const MESSAGE_SUBJECT_MAX_CHARS: usize = 200;
/// Supporting evidence cap for cross-project messages (#1428).
const MESSAGE_EVIDENCE_MAX_CHARS: usize = 1_000;

#[derive(Debug, Deserialize)]
struct PendingWritesQuery {
    workspace: String,
    project: String,
    #[serde(default)]
    status: Option<String>,
    #[serde(default = "default_pending_writes_limit")]
    limit: usize,
}

fn default_pending_writes_limit() -> usize {
    50
}

#[derive(Debug, Deserialize)]
struct PendingWriteScopeQuery {
    workspace: String,
    project: String,
}

#[derive(Debug, Deserialize)]
struct PendingRejectRequest {
    #[serde(default)]
    reason: String,
}

fn default_auto_improve_min_observations() -> usize {
    ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MIN_OBSERVATIONS
}

fn default_auto_improve_min_session_duration_secs() -> u64 {
    ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MIN_SESSION_DURATION_SECS
}

fn default_auto_improve_min_confidence() -> f32 {
    ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MIN_CONFIDENCE
}

fn default_auto_improve_max_input_tokens() -> usize {
    ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_INPUT_TOKENS
}

fn default_auto_improve_max_proposals() -> usize {
    ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_PROPOSALS
}

fn default_auto_improve_max_patchable_pages() -> usize {
    ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_PATCHABLE_PAGES
}

fn default_auto_improve_max_patchable_body_chars() -> usize {
    ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_PATCHABLE_BODY_CHARS
}

fn default_auto_improve_max_edits_per_proposal() -> usize {
    ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_EDITS_PER_PROPOSAL
}

fn default_auto_improve_max_edit_content_chars() -> usize {
    ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_EDIT_CONTENT_CHARS
}

fn default_auto_improve_max_changed_chars_per_proposal() -> usize {
    ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_CHANGED_CHARS_PER_PROPOSAL
}

fn default_auto_improve_max_patch_edits_per_run() -> usize {
    ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_PATCH_EDITS_PER_RUN
}

fn default_auto_improve_max_rejection_context() -> usize {
    ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_REJECTION_CONTEXT
}

fn default_auto_improve_rejection_context_days() -> u32 {
    ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_REJECTION_CONTEXT_DAYS
}

fn default_auto_improve_max_final_body_chars() -> usize {
    ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_FINAL_BODY_CHARS
}

fn default_auto_improve_max_rule_page_tokens() -> usize {
    ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_RULE_PAGE_TOKENS
}

fn default_auto_improve_max_procedure_page_tokens() -> usize {
    ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_PROCEDURE_PAGE_TOKENS
}

fn default_auto_improve_proposal_actor() -> String {
    ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_PROPOSAL_ACTOR.into()
}

fn default_auto_improve_pending_path() -> String {
    ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_PENDING_PATH.into()
}

fn default_auto_improve_telemetry_since_days() -> u32 {
    ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_TELEMETRY_SINCE_DAYS
}

fn default_auto_improve_telemetry_top_limit() -> usize {
    ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_TELEMETRY_TOP_LIMIT
}

fn hex_to_sha256(hex: &str) -> Result<[u8; 32], String> {
    if hex.len() != 64 {
        return Err("expected 64 hex chars".into());
    }
    let mut out = [0_u8; 32];
    for (idx, chunk) in hex.as_bytes().chunks_exact(2).enumerate() {
        let s = std::str::from_utf8(chunk).map_err(|e| e.to_string())?;
        out[idx] = u8::from_str_radix(s, 16).map_err(|e| e.to_string())?;
    }
    Ok(out)
}

/// Build the admin axum [`Router`]. Mounts:
/// - `POST /admin/backup`
/// - `POST /admin/bootstrap`
/// - `POST /admin/auto-improve`
/// - `POST /admin/auto-improve/report`
/// - `POST /admin/curator`
/// - `GET  /admin/status`
/// - `GET  /admin/metrics`
/// - `GET  /admin/projects`
/// - `GET  /admin/project-coordinate`
/// - `GET  /admin/open-sessions`
/// - `GET  /admin/sessions/by-agent`
/// - `GET  /admin/activity/by-client`
/// - `GET  /admin/audit-contamination`
/// - `GET  /admin/search`
/// - `GET  /admin/recent`
/// - `GET  /admin/read-page`
/// - `POST /admin/reorg`
/// - `POST /admin/lint`
/// - `POST /admin/forget-sweep`
/// - `POST /admin/embed`
/// - `POST /admin/commit`
/// - `GET  /admin/checkpoints`
/// - `POST /admin/restore-page`
/// - `POST /admin/purge-project`
/// - `POST /admin/rename-project`
/// - `POST /admin/move-project`
/// - `POST /admin/move-session`
/// - `POST /admin/repair-session-times`
/// - `POST /admin/merge-workspace`
/// - `POST /admin/write-page`
/// - `POST /admin/delete-page`
/// - user-management routes under `/admin/users*`
pub fn admin_router(state: AdminState) -> Router {
    admin_router_with_decay_breadth(state, 0.0)
}

/// Build the admin router with the optional distinct-reader retention weight.
pub fn admin_router_with_decay_breadth(state: AdminState, breadth_weight: f64) -> Router {
    admin_router_with_sweep_tuning(
        state,
        breadth_weight,
        ObservationRetention::default(),
        LedgerRetention::default(),
        false,
    )
}

/// Build the admin router with every sweep knob that lives outside
/// `DecayParams`, including the opt-in observation prune (disabled by default),
/// the opt-in event ledger age sweep (disabled by default) and A2 extractive
/// tier-down (`compact_cold_episodic`, off by default).
pub fn admin_router_with_sweep_tuning(
    state: AdminState,
    breadth_weight: f64,
    retention: ObservationRetention,
    ledger_retention: LedgerRetention,
    compact_cold_episodic: bool,
) -> Router {
    let state = Arc::new(state);
    let operational = Router::new()
        .route("/admin/backup", post(handle_backup))
        .route("/admin/export-okf", post(handle_export_okf))
        .route("/admin/bootstrap", post(handle_bootstrap))
        .route("/admin/auto-improve", post(handle_auto_improve))
        .route(
            "/admin/auto-improve/report",
            post(handle_auto_improve_report),
        )
        .route("/admin/curator", post(handle_curator))
        .route("/admin/handoffs", get(handle_open_handoffs_list))
        .route("/admin/handoffs/expire", post(handle_expire_handoffs))
        .route("/admin/messages", get(handle_list_messages))
        .route("/admin/messages/send", post(handle_send_message))
        .route("/admin/messages/pop", post(handle_pop_message))
        .route("/admin/messages/cancel", post(handle_cancel_messages))
        .route("/admin/pending-writes", get(handle_pending_writes_list))
        .route(
            "/admin/pending-writes/{id}",
            get(handle_pending_write_detail),
        )
        .route(
            "/admin/pending-writes/{id}/diff",
            get(handle_pending_write_diff),
        )
        .route(
            "/admin/pending-writes/{id}/approve",
            post(handle_pending_write_approve),
        )
        .route(
            "/admin/pending-writes/{id}/reject",
            post(handle_pending_write_reject),
        )
        .route("/admin/status", get(handle_status))
        .route("/admin/llm-test", post(handle_llm_test))
        .route("/admin/metrics", get(handle_metrics))
        .route("/admin/projects", get(handle_list_projects))
        .route("/admin/project-coordinate", get(handle_project_coordinate))
        .route("/admin/open-sessions", get(handle_open_sessions))
        .route("/admin/sessions/by-agent", get(handle_sessions_by_agent))
        .route("/admin/activity/by-client", get(handle_activity_by_client))
        .route(
            "/admin/audit-contamination",
            get(handle_audit_contamination),
        )
        .route("/admin/audit-log", get(handle_audit_log))
        .route("/admin/search", get(handle_search))
        .route("/admin/recent", get(handle_recent))
        .route("/admin/read-page", get(handle_read_page))
        .route("/admin/reorg", post(handle_reorg))
        .route("/admin/lint", post(handle_lint))
        .route("/admin/forget-sweep", post(handle_forget_sweep))
        .route("/admin/embed", post(handle_embed))
        .route("/admin/commit", post(handle_commit))
        .route("/admin/checkpoints", get(handle_checkpoints))
        .route("/admin/restore-page", post(handle_restore_page))
        .route("/admin/purge-project", post(handle_purge_project))
        .route("/admin/purge-session", post(handle_purge_session))
        .route("/admin/rename-project", post(handle_rename_project))
        .route("/admin/move-project", post(handle_move_project))
        .route("/admin/merge-project", post(handle_merge_project))
        .route("/admin/move-session", post(handle_move_session))
        .route(
            "/admin/repair-session-times",
            post(handle_repair_session_times),
        )
        .route("/admin/delete-workspace", post(handle_delete_workspace))
        .route("/admin/compact", post(handle_compact))
        .route(
            "/admin/reclaim-ledger-versions",
            post(handle_reclaim_ledger_versions),
        )
        .route("/admin/rename-workspace", post(handle_rename_workspace))
        .route("/admin/merge-workspace", post(handle_merge_workspace))
        .route("/admin/write-page", post(handle_write_page))
        .route("/admin/delete-page", post(handle_delete_page));
    let users = Router::new()
        .route("/admin/users", get(handle_list_users))
        .route("/admin/human-users", post(handle_create_human_user))
        .route("/admin/users/{username}", patch(handle_patch_user))
        .route(
            "/admin/users/{username}/reset-password",
            post(handle_reset_password),
        )
        .route("/admin/users/{username}/disable", post(handle_disable_user))
        .route("/admin/users/{username}/enable", post(handle_enable_user))
        .route(
            "/admin/api-credentials",
            get(handle_list_api_credentials).post(handle_create_api_credential),
        )
        .route(
            "/admin/api-credentials/{id}/rotate",
            post(handle_rotate_api_credential),
        )
        .route(
            "/admin/api-credentials/{id}/revoke",
            post(handle_revoke_api_credential),
        )
        .route("/admin/users/{username}/grant", post(handle_user_grant))
        .route("/admin/users/{username}/revoke", post(handle_user_revoke))
        .route(
            "/admin/users/{username}/grants",
            get(handle_list_user_grants),
        )
        .route("/admin/projects/grants", get(handle_list_project_grants))
        .route("/admin/projects/access", post(handle_project_access));
    operational
        .merge(users)
        .route_layer(axum::middleware::from_fn_with_state(
            state.clone(),
            require_root_for_multiuser_admin,
        ))
        .with_state(state)
        .layer(axum::Extension(SweepTuning {
            breadth_weight,
            retention,
            ledger_retention,
            compact_cold_episodic,
        }))
}

async fn require_root_for_multiuser_admin(
    State(state): State<Arc<AdminState>>,
    req: axum::http::Request<Body>,
    next: Next,
) -> Response {
    let level = req
        .extensions()
        .get::<ai_memory_core::AuthLevel>()
        .copied()
        .unwrap_or(ai_memory_core::AuthLevel::Anonymous);
    // Read this for every request rather than caching a post-creation flag: a
    // committed first user immediately closes bootstrap admin access, including
    // across concurrent requests and without a server restart.
    //
    // Same notion of "this deployment distinguishes operators" the MCP admin
    // gate uses. Keyed on `users_exist()` alone, a trusted-proxy deployment
    // with no `users` rows would wave a proxy-asserted `AuthLevel::User` caller
    // through every operational route below — purge, delete-page, backup — and
    // only `/admin/users*` would survive on its own inner root check.
    let distinguishes_operators = match state
        .reader
        .distinguishes_operators(state.trusted_proxy_identity)
        .await
    {
        Ok(exists) => exists,
        Err(error) => {
            tracing::error!(%error, "admin authorization could not determine whether users exist");
            return (
                StatusCode::INTERNAL_SERVER_ERROR,
                Json(serde_json::json!({
                    "error": "admin authorization unavailable: could not verify user configuration"
                })),
            )
                .into_response();
        }
    };
    match level.authorize(Capability::Admin, distinguishes_operators) {
        Ok(()) => next.run(req).await,
        Err(e) => (
            authz_status(e),
            Json(serde_json::json!({ "error": e.message() })),
        )
            .into_response(),
    }
}

fn authz_status(err: ai_memory_core::AuthzError) -> StatusCode {
    if err.is_authentication_required() {
        StatusCode::UNAUTHORIZED
    } else {
        StatusCode::FORBIDDEN
    }
}

// ---------------------------------------------------------------------
// backup
// ---------------------------------------------------------------------

/// Handler for `POST /admin/backup`.
///
/// Snapshots the live SQLite DB via the online backup API, then
/// tar-gzips `wiki/`, the snapshot, and `config.toml` (if present)
/// into a tempfile. The response streams the file instead of buffering
/// the full archive in memory.
async fn handle_backup(State(state): State<Arc<AdminState>>) -> Response {
    match build_backup_tarball_file(&state).await {
        Ok(file) => Response::builder()
            .status(StatusCode::OK)
            .header(header::CONTENT_TYPE, "application/gzip")
            .header(
                header::CONTENT_DISPOSITION,
                "attachment; filename=\"backup.tar.gz\"",
            )
            .body(Body::from_stream(ReaderStream::new(file)))
            .unwrap_or_else(|_| {
                Response::builder()
                    .status(StatusCode::INTERNAL_SERVER_ERROR)
                    .body(Body::empty())
                    .unwrap_or_else(|_| StatusCode::INTERNAL_SERVER_ERROR.into_response())
            }),
        Err(e) => {
            warn!(error = %e, "backup failed");
            let body = serde_json::to_vec(&serde_json::json!({ "error": e.to_string() }))
                .unwrap_or_default();
            Response::builder()
                .status(StatusCode::INTERNAL_SERVER_ERROR)
                .header(header::CONTENT_TYPE, "application/json")
                .body(Body::from(body))
                .unwrap_or_else(|_| {
                    Response::builder()
                        .status(StatusCode::INTERNAL_SERVER_ERROR)
                        .body(Body::empty())
                        .unwrap_or_else(|_| StatusCode::INTERNAL_SERVER_ERROR.into_response())
                })
        }
    }
}

async fn build_backup_tarball_file(state: &AdminState) -> anyhow::Result<tokio::fs::File> {
    let wiki_dir = state.data_dir.join("wiki");
    ai_memory_wiki::validate_wiki_tree(&wiki_dir)
        .map_err(|error| anyhow::anyhow!("validating wiki tree: {error}"))?;
    let staging = tempfile::tempdir()?;
    let snapshot_path = staging.path().join("memory.sqlite");
    info!(snapshot = %snapshot_path.display(), "snapshotting SQLite for backup");
    state
        .reader
        .snapshot_to(snapshot_path.clone())
        .await
        .map_err(|e| anyhow::anyhow!("sqlite snapshot: {e}"))?;

    let mut tar_file = tempfile::tempfile()?;
    {
        let encoder = GzEncoder::new(&mut tar_file, Compression::default());
        let mut tar = tar::Builder::new(encoder);
        tar.mode(tar::HeaderMode::Deterministic);
        tar.follow_symlinks(false);

        ai_memory_wiki::validate_wiki_tree(&wiki_dir)
            .map_err(|error| anyhow::anyhow!("validating wiki tree before archive: {error}"))?;
        if wiki_dir.is_dir() {
            tar.append_dir_all("wiki", &wiki_dir)
                .map_err(|e| anyhow::anyhow!("archiving wiki/: {e}"))?;
        }

        tar.append_path_with_name(&snapshot_path, "db/memory.sqlite")
            .map_err(|e| anyhow::anyhow!("archiving db snapshot: {e}"))?;

        let cfg = state.data_dir.join("config.toml");
        if cfg.is_file() {
            tar.append_path_with_name(&cfg, "config.toml")
                .map_err(|e| anyhow::anyhow!("archiving config.toml: {e}"))?;
        }

        let encoder = tar.into_inner()?;
        encoder.finish()?;
    }
    tar_file.sync_data()?;
    tar_file.rewind()?;
    Ok(tokio::fs::File::from_std(tar_file))
}

// ---------------------------------------------------------------------
// export-okf
// ---------------------------------------------------------------------

/// Query for `POST /admin/export-okf`: the one project bundle to export.
#[derive(Deserialize)]
struct ExportOkfQuery {
    workspace: String,
    project: String,
}

/// `POST /admin/export-okf?workspace=…&project=…` — stream the project
/// directory as an OKF v0.2 bundle tarball (docs/okf.md). The wiki files
/// ARE the bundle (native conformance), so this is a validated copy with
/// a freshly generated `index.md` (full listing + `okf_version`). Any
/// non-conformant page file fails the export rather than shipping a
/// bundle a strict reader would reject.
async fn handle_export_okf(
    State(state): State<Arc<AdminState>>,
    Query(q): Query<ExportOkfQuery>,
) -> Response {
    let ids = match lookup_ws_proj_no_create(&state, q.workspace.trim(), q.project.trim()).await {
        Ok(ids) => ids,
        Err((status, body)) => return (status, body).into_response(),
    };
    match build_okf_bundle_file(&state, ids.0, ids.1, q.project.trim()).await {
        Ok(file) => Response::builder()
            .status(StatusCode::OK)
            .header(header::CONTENT_TYPE, "application/gzip")
            .header(
                header::CONTENT_DISPOSITION,
                "attachment; filename=\"okf-bundle.tar.gz\"",
            )
            .body(Body::from_stream(ReaderStream::new(file)))
            .unwrap_or_else(|_| StatusCode::INTERNAL_SERVER_ERROR.into_response()),
        Err(e) => {
            warn!(error = %e, "okf export failed");
            let body = serde_json::to_vec(&serde_json::json!({ "error": e.to_string() }))
                .unwrap_or_default();
            Response::builder()
                .status(StatusCode::UNPROCESSABLE_ENTITY)
                .header(header::CONTENT_TYPE, "application/json")
                .body(Body::from(body))
                .unwrap_or_else(|_| StatusCode::INTERNAL_SERVER_ERROR.into_response())
        }
    }
}

async fn build_okf_bundle_file(
    state: &AdminState,
    ws: ai_memory_core::WorkspaceId,
    proj: ai_memory_core::ProjectId,
    project_name: &str,
) -> anyhow::Result<tokio::fs::File> {
    state.wiki.validate_project_tree(ws, proj)?;
    let bundle_dir = state.wiki.project_root(ws, proj);
    if !bundle_dir.is_dir() {
        anyhow::bail!("project has no wiki directory yet");
    }

    // Validate + collect: every non-reserved .md must be conformant. Keep
    // the raw bytes read here (rather than re-reading from disk below) —
    // the export augments a page's frontmatter/body only in the tarred
    // copy, so the file is read exactly once.
    let mut files: Vec<(std::path::PathBuf, String)> = Vec::new();
    let mut families: Vec<String> = Vec::new();
    let mut stack = vec![bundle_dir.clone()];
    while let Some(dir) = stack.pop() {
        for entry in std::fs::read_dir(&dir)? {
            let entry = entry?;
            let path = entry.path();
            let ft = entry.file_type()?;
            if ft.is_dir() {
                // `_pending/` is the auto-improve staging area — proposal
                // sidecars, not concept files; a strict OKF reader has no
                // business seeing them (post-audit finding: an unresolved
                // pending proposal blocked every export).
                if entry.file_name() == "_pending" {
                    continue;
                }
                if dir == bundle_dir {
                    families.push(entry.file_name().to_string_lossy().into_owned());
                }
                stack.push(path);
            } else if ft.is_file() && path.extension().is_some_and(|e| e == "md") {
                let name = path.file_name().and_then(|n| n.to_str()).unwrap_or("");
                if name == "index.md" || name == "log.md" {
                    continue; // regenerated / not adopted
                }
                // A rotated event ledger is the same raw hook capture as the
                // `log.md` above, only past a month boundary — it carries no
                // frontmatter, so the conformance gate below failed the whole
                // export for every project that ever captured an observation
                // (#748). The check is content-gated exactly like the
                // migration scan's (#669), so a prose page that happens to be
                // named `log-2026-09.md` still ships and still has to conform.
                if ai_memory_wiki::is_rotated_event_ledger(&path) {
                    continue;
                }
                let raw = std::fs::read_to_string(&path)?;
                let fm = ai_memory_wiki::parse(&raw)
                    .map(|m| m.frontmatter)
                    .unwrap_or_default();
                if !ai_memory_core::okf::is_conformant(&fm) {
                    anyhow::bail!(
                        "page {} is not OKF-conformant; run the server once to migrate \
                         before exporting",
                        path.strip_prefix(&bundle_dir).unwrap_or(&path).display()
                    );
                }
                files.push((path, raw));
            }
        }
    }

    let mut tar_file = tempfile::tempfile()?;
    {
        let encoder = GzEncoder::new(&mut tar_file, Compression::default());
        let mut tar = tar::Builder::new(encoder);
        tar.mode(tar::HeaderMode::Deterministic);
        tar.follow_symlinks(false);
        // Fresh bundle-root index.md: okf_version + full listing, with no
        // prose outside the list structure (some strict OKF validators
        // read §11.3 as rejecting a stray sentence — issue #960 item 1).
        families.sort();
        let listing = ai_memory_wiki::okf_directory_listing(&families);
        let index = format!(
            "---\nokf_version: \"0.2\"\n---\n\n# Bundle index — concept files by directory\n\n{listing}"
        );
        let mut header = tar::Header::new_gnu();
        header.set_size(index.len() as u64);
        header.set_mode(0o644);
        header.set_cksum();
        tar.append_data(&mut header, "index.md", index.as_bytes())?;
        for (path, raw) in files {
            let rel = path.strip_prefix(&bundle_dir).unwrap_or(&path);
            let rel_str = rel.to_string_lossy().replace('\\', "/");
            let bytes = augment_page_for_export(&raw, &rel_str, project_name)?;
            let mut header = tar::Header::new_gnu();
            header.set_size(bytes.len() as u64);
            header.set_mode(0o644);
            header.set_cksum();
            tar.append_data(&mut header, &rel_str, bytes.as_slice())?;
        }
        let encoder = tar.into_inner()?;
        encoder.finish()?;
    }
    tar_file.sync_data()?;
    tar_file.rewind()?;
    Ok(tokio::fs::File::from_std(tar_file))
}

/// Export-only augmentation of one wiki page's bytes for the OKF bundle:
/// backfills `title`/`description` when derivable and rewrites local
/// wikilinks to bundle-relative Markdown links (issue #960 items 2 and 3).
/// Never touches the on-disk wiki file — the caller tars the returned
/// bytes instead of the source file.
fn augment_page_for_export(
    raw: &str,
    rel_path: &str,
    project_name: &str,
) -> anyhow::Result<Vec<u8>> {
    let page_path = ai_memory_core::PagePath::new(rel_path.to_string())?;
    let mut md = ai_memory_wiki::parse(raw)?;

    let title_missing = md
        .frontmatter
        .get("title")
        .and_then(serde_json::Value::as_str)
        .is_none_or(|t| t.trim().is_empty());
    let title =
        title_missing.then(|| ai_memory_wiki::derive_title(&md.frontmatter, &md.body, &page_path));

    let description_missing = md
        .frontmatter
        .get("description")
        .and_then(serde_json::Value::as_str)
        .is_none_or(|d| d.trim().is_empty());
    let description = description_missing
        .then(|| {
            md.frontmatter
                .get("summary")
                .and_then(serde_json::Value::as_str)
                .filter(|s| !s.trim().is_empty())
                .or_else(|| {
                    md.frontmatter
                        .get("abstract")
                        .and_then(serde_json::Value::as_str)
                        .filter(|s| !s.trim().is_empty())
                })
                .map(str::to_string)
        })
        .flatten();

    if !md.frontmatter.is_object() {
        md.frontmatter = serde_json::Value::Object(serde_json::Map::new());
    }
    let map = md
        .frontmatter
        .as_object_mut()
        .expect("object ensured above");
    if let Some(title) = title {
        map.insert("title".into(), serde_json::Value::String(title));
    }
    if let Some(description) = description {
        map.insert("description".into(), serde_json::Value::String(description));
    }

    md.body = ai_memory_wiki::rewrite_local_wikilinks(&md.body, &page_path, project_name);

    Ok(ai_memory_wiki::emit(&md)?.into_bytes())
}

// ---------------------------------------------------------------------
// status
// ---------------------------------------------------------------------

/// Query string for `GET /admin/audit-contamination`. Supplying BOTH
/// `workspace` and `project` scopes the audit to that one landed bucket;
/// omit both to audit every project.
#[derive(Deserialize)]
struct AuditContaminationQuery {
    workspace: Option<String>,
    project: Option<String>,
}

/// `GET /admin/audit-contamination` — read-only structural contamination audit
/// (see [`ai_memory_store::ReaderPool::audit_contamination`]). Reports likely
/// cross-project mislandings (a session whose cwd resolves elsewhere; an
/// observation whose project disagrees with its session); never mutates, so it
/// is safe to run on any cadence (e.g. a cron probe alerting on non-zero counts).
async fn handle_audit_contamination(
    State(state): State<Arc<AdminState>>,
    Query(q): Query<AuditContaminationQuery>,
) -> impl IntoResponse {
    let scope = match (
        trimmed_opt(q.workspace.as_deref()),
        trimmed_opt(q.project.as_deref()),
    ) {
        (Some(ws), Some(proj)) => match lookup_ws_proj_no_create(&state, ws, proj).await {
            Ok(ids) => Some(ids),
            Err(e) => return e,
        },
        (Some(_), None) | (None, Some(_)) => {
            return (
                StatusCode::BAD_REQUEST,
                Json(serde_json::json!({
                    "error": "workspace and project must be provided together"
                })),
            );
        }
        _ => None,
    };
    match state
        .reader
        .audit_contamination(scope, state.home_dir.as_deref())
        .await
    {
        Ok(report) => (
            StatusCode::OK,
            Json(serde_json::to_value(&report).unwrap_or_else(|_| serde_json::json!({}))),
        ),
        Err(e) => (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(serde_json::json!({ "error": e.to_string() })),
        ),
    }
}

/// Query string for `GET /admin/audit-log`. Names are optional independent
/// filters; when both workspace and project are present they are resolved
/// through [`lookup_existing_scope`] so a typo fails closed (404) instead of
/// looking like an empty log.
#[derive(Debug, Deserialize)]
struct AuditLogQuery {
    workspace: Option<String>,
    project: Option<String>,
    op: Option<String>,
    before_id: Option<i64>,
    #[serde(default = "default_audit_log_limit")]
    limit: usize,
}

fn default_audit_log_limit() -> usize {
    50
}

/// `GET /admin/audit-log` — read-only paginated trail of the existing
/// `audit_log` table. `detail` is returned for schema fidelity; it is not a
/// payload (the only writer stores the literal `{}`).
async fn handle_audit_log(
    State(state): State<Arc<AdminState>>,
    Query(q): Query<AuditLogQuery>,
) -> impl IntoResponse {
    let workspace = trimmed_opt(q.workspace.as_deref()).map(str::to_owned);
    let project = trimmed_opt(q.project.as_deref()).map(str::to_owned);
    if let (Some(ws), Some(proj)) = (workspace.as_deref(), project.as_deref()) {
        match lookup_ws_proj_no_create(&state, ws, proj).await {
            Ok(_) => {}
            Err(e) => return e,
        }
    }
    let filter = AuditLogFilter {
        workspace,
        project,
        op: trimmed_opt(q.op.as_deref()).map(str::to_owned),
        before_id: q.before_id,
        limit: q.limit,
    };
    match state.reader.list_audit_events(filter).await {
        Ok(events) => (
            StatusCode::OK,
            Json(
                serde_json::to_value(&events)
                    .map(|list| serde_json::json!({ "events": list }))
                    .unwrap_or_else(|_| serde_json::json!({ "events": [] })),
            ),
        ),
        Err(e) => (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(serde_json::json!({ "error": e.to_string() })),
        ),
    }
}

/// Handler for `GET /admin/metrics`: process counters and latency
/// histograms in the Prometheus text format. Root-only on a multi-user server
/// through the same gate as every `/admin/*` route. Content-free by
/// construction: see [`crate::metrics`].
async fn handle_metrics(State(state): State<Arc<AdminState>>) -> Response {
    (
        [(
            header::CONTENT_TYPE,
            crate::metrics::PROMETHEUS_CONTENT_TYPE,
        )],
        crate::metrics::render_prometheus(&state.ingest_metrics, &state.mcp_metrics),
    )
        .into_response()
}

/// JSON response body for `GET /admin/status`. The CLI's `status`
/// subcommand renders this either as JSON (`--json`) or as a small
/// human-friendly text block.
#[derive(Debug, Serialize)]
pub struct StatusReport {
    /// Server binary version (Cargo package version).
    pub version: String,
    /// Absolute data directory the server uses (server-side path).
    pub data_dir: String,
    /// Bind address the HTTP transport is listening on.
    pub bind: String,
    /// Absolute SQLite path inside `data_dir`.
    pub db_path: String,
    /// Lifetime counts: pages_latest, pages_all, sessions, observations.
    pub counts: ai_memory_store::StatusCounts,
    /// Derived-index and retrieval-readiness diagnostics.
    pub derived: ai_memory_store::DerivedIndexStatus,
    /// Physical storage figures — file size and reclaimable free pages — so an
    /// operator can decide whether a `VACUUM` is worth its exclusive lock.
    pub storage: ai_memory_store::StorageStatus,
    /// Passive process-scoped provider health.
    pub providers: ProviderHealthSnapshot,
    /// Hook-ingestion counters for this server process. Counts and one
    /// timestamp only — never captured content (#428).
    pub ingest: ai_memory_core::IngestMetricsSnapshot,
    /// Instantaneous write-queue depth `(queued, capacity)` — the
    /// wedged-writer signal (2.0 item 7).
    pub write_queue: (usize, usize),
    /// Wiki-format state: whether the OKF migration has run, and the
    /// pre-migration backup archive if its receipt still exists.
    pub wiki_format: WikiFormatStatus,
    /// SessionEnd consolidation queue: counts plus the sessions that gave up,
    /// so a watchdog can re-run them once the cause is fixed (#1692).
    pub consolidation: ConsolidationStatus,
}

/// Consolidation section of [`StatusReport`].
#[derive(Debug, serde::Serialize, serde::Deserialize)]
pub struct ConsolidationStatus {
    /// Jobs waiting for a worker, including ones backing off to retry.
    pub pending: u64,
    /// Jobs a worker holds right now.
    pub running: u64,
    /// Jobs that finished.
    pub completed: u64,
    /// Jobs that gave up after their attempts.
    pub failed: u64,
    /// Most recent failures, newest first, bounded to
    /// [`CONSOLIDATION_FAILED_SESSIONS_CAP`]. The session id is what a
    /// re-consolidation needs; the error is the worker's own bounded text,
    /// scrubbed before it leaves the server.
    pub failed_sessions: Vec<FailedConsolidationSession>,
}

/// One failed session in [`ConsolidationStatus::failed_sessions`].
#[derive(Debug, serde::Serialize, serde::Deserialize)]
pub struct FailedConsolidationSession {
    /// Session whose consolidation gave up.
    pub session_id: String,
    /// Provider attempts spent on it.
    pub attempts: u32,
    /// Unix microseconds of the final failure.
    pub failed_at_us: i64,
    /// Bounded, scrubbed error the worker recorded.
    pub last_error: String,
}

/// How many failed sessions one status response carries. The counts above
/// stay exact; the list is a sample, newest first, so the payload cannot grow
/// with the backlog.
pub const CONSOLIDATION_FAILED_SESSIONS_CAP: u32 = 20;
/// Longest error text one failed session carries, in characters.
const CONSOLIDATION_ERROR_CHARS: usize = 200;

/// Wiki-format section of [`StatusReport`].
#[derive(Debug, serde::Serialize, serde::Deserialize)]
pub struct WikiFormatStatus {
    /// True once the OKF v0.2 wiki migration has been applied.
    pub okf_migrated: bool,
    /// Pre-migration backup archive path, when the receipt exists AND
    /// the archive file is still on disk.
    pub backup_archive: Option<String>,
    /// Size of that archive in bytes.
    pub backup_archive_bytes: Option<u64>,
}

/// `GET /admin/projects` — the authoritative list of `(workspace, project)`
/// pairs (with page counts + last-updated), read-only. Useful to any external
/// consumer that needs the live project inventory: a dashboard, an export, or
/// a backup/mirror that lays the wiki out as `wiki/<workspace>/<project>/` and
/// wants to reconcile against it — any directory whose project no longer
/// appears here is an orphan (e.g. from a delete that bypassed the admission
/// chain, such as an offline `--data-dir` purge or a direct DB edit) and can
/// be pruned so the copy reflects the live server.
async fn handle_list_projects(State(state): State<Arc<AdminState>>) -> impl IntoResponse {
    match state.reader.list_projects_with_stats(OPERATOR).await {
        Ok(projects) => (
            StatusCode::OK,
            Json(serde_json::json!({ "projects": projects })),
        ),
        Err(e) => internal_err(e.to_string()),
    }
}

/// `POST /admin/llm-test` — probe the server's own configured chat provider.
///
/// `ai-memory llm-test` builds a provider from the *caller's* environment,
/// which is the wrong one when the server runs in a container or on another
/// host: its keys exist only there, so following the health report's retry
/// hint failed while the server was healthy (#1639). This runs the provider
/// the server configured, with a fixed short prompt, and answers with the
/// same status class and bounded message the health snapshot records — never
/// the request, the reply text or the provider's full body.
async fn handle_llm_test(State(state): State<Arc<AdminState>>) -> Response {
    let Some(llm) = state.llm.clone() else {
        return (
            StatusCode::SERVICE_UNAVAILABLE,
            Json(serde_json::json!({
                "error": "this server has no LLM provider configured; set one in its config and restart it",
            })),
        )
            .into_response();
    };
    let mut request = ChatRequest::user_prompt("ping".to_owned());
    request.temperature = Some(0.2);
    let started = std::time::Instant::now();
    let elapsed = |started: std::time::Instant| started.elapsed().as_millis() as u64;
    match llm.complete(request).await {
        Ok(response) => Json(serde_json::json!({
            "ok": true,
            "provider": llm.name(),
            "model": response.model,
            "latency_ms": elapsed(started),
            "reply_chars": response.text.chars().count(),
        }))
        .into_response(),
        Err(error) => {
            let (status, message) = error_status_and_message(&error);
            // A provider body can quote the key it rejected. The health
            // snapshot's own copy is bounded but not scrubbed; this one is
            // printed into an operator's terminal, so it goes through the
            // privacy strip first.
            let message = state.wiki.sanitizer().scrub(&message);
            (
                StatusCode::BAD_GATEWAY,
                Json(serde_json::json!({
                    "ok": false,
                    "provider": llm.name(),
                    "model": llm.model(),
                    "latency_ms": elapsed(started),
                    "error": message,
                    "status": status,
                })),
            )
                .into_response()
        }
    }
}

async fn handle_status(State(state): State<Arc<AdminState>>) -> impl IntoResponse {
    // Count "missing" against the configured embedder's stored triple, so
    // a model swap cannot read as a fully covered index; with no embedder
    // configured the historical "no vector at all" count is kept.
    let configured_embedding = state.embedder.as_deref().map(stored_embedding_identity);
    match state.reader.status_counts().await {
        Ok(counts) => match match configured_embedding {
            Some(identity) => {
                state
                    .reader
                    .derived_index_status_for_embedding(identity)
                    .await
            }
            None => state.reader.derived_index_status().await,
        } {
            Ok(derived) => {
                // Three pragma reads; a failure here must not take down the
                // whole status response, which is also the health probe.
                let storage = state.reader.storage_status().await.unwrap_or_default();
                let okf_migrated = state
                    .reader
                    .wiki_migration_names()
                    .await
                    .map(|names| names.iter().any(|n| n.contains("okf")))
                    .unwrap_or(false);
                let backup = ai_memory_wiki::backup::BackupReceipt::load(&state.data_dir)
                    .filter(ai_memory_wiki::backup::BackupReceipt::archive_present);
                let consolidation =
                    consolidation_status(&state, &state.reader.session_consolidation_queue().await)
                        .await;
                let report = StatusReport {
                    version: env!("CARGO_PKG_VERSION").to_string(),
                    data_dir: state.data_dir.display().to_string(),
                    bind: state.bind.clone(),
                    db_path: state.db_path.display().to_string(),
                    counts,
                    derived,
                    storage,
                    providers: state.provider_health.snapshot(),
                    ingest: state.ingest_metrics.snapshot(),
                    write_queue: state.writer.queue_depth(),
                    wiki_format: WikiFormatStatus {
                        okf_migrated,
                        backup_archive: backup
                            .as_ref()
                            .map(|r| r.archive_path.display().to_string()),
                        backup_archive_bytes: backup.as_ref().map(|r| r.size_bytes),
                    },
                    consolidation,
                };
                (
                    StatusCode::OK,
                    Json(serde_json::to_value(&report).unwrap_or_else(|_| serde_json::json!({}))),
                )
            }
            Err(e) => (
                StatusCode::INTERNAL_SERVER_ERROR,
                Json(serde_json::json!({ "error": e.to_string() })),
            ),
        },
        Err(e) => (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(serde_json::json!({ "error": e.to_string() })),
        ),
    }
}

/// The consolidation section of a status report.
///
/// A failure to read the queue degrades to zeros, like the storage figures
/// above: `status` is also the health probe, and a queue query must not take
/// the whole answer down.
async fn consolidation_status(
    state: &AdminState,
    queue: &Result<ai_memory_store::SessionConsolidationQueue, ai_memory_store::StoreError>,
) -> ConsolidationStatus {
    let queue = queue.as_ref().copied().unwrap_or_default();
    let failed_sessions = match state
        .reader
        .failed_consolidation_jobs(CONSOLIDATION_FAILED_SESSIONS_CAP)
        .await
    {
        Ok(jobs) => jobs
            .into_iter()
            .map(|job| FailedConsolidationSession {
                session_id: job.session_id,
                attempts: job.attempts,
                failed_at_us: job.failed_at_us,
                // The worker truncates what it records, but that text comes
                // from a provider body: scrub it before an operator's terminal
                // sees it, exactly like `/admin/llm-test`.
                last_error: state
                    .wiki
                    .sanitizer()
                    .scrub(&job.last_error)
                    .chars()
                    .take(CONSOLIDATION_ERROR_CHARS)
                    .collect(),
            })
            .collect(),
        Err(_) => Vec::new(),
    };
    ConsolidationStatus {
        pending: queue.pending,
        running: queue.running,
        completed: queue.completed,
        failed: queue.failed,
        failed_sessions,
    }
}

// ---------------------------------------------------------------------
// open-sessions
// ---------------------------------------------------------------------

/// Query string for `GET /admin/open-sessions` — open (not yet ended)
/// sessions for one scope + agent, newest first. Backs the thin
/// `ai-memory finalize-session` command, which posts synthetic
/// session-end hooks for whatever this returns. An exact `session_id` plus
/// `include_ended=true` also matches an already-ended session, for the
/// manual re-finalize path (`finalize-session --reopen`).
#[derive(Debug, Deserialize)]
struct OpenSessionsQuery {
    /// Workspace name (required).
    workspace: String,
    /// Project name (required).
    project: String,
    /// Agent kind filter, kebab-case (`codex`, `claude-code`, …).
    agent: String,
    /// When true, return every open session; otherwise just the newest.
    #[serde(default)]
    all: bool,
    /// Include sessions belonging to OTHER operators.
    ///
    /// Off by default because the caller of this endpoint (`finalize-session`)
    /// acts destructively on what it returns: it ends the session, synthesises
    /// a page from its observations and mints a handoff carrying its raw
    /// prompts. Picking "the newest open session in the scope" across everyone
    /// would do all of that to a colleague's live session. Sessions with no
    /// recorded operator stay visible either way, so a single-operator server
    /// is unaffected.
    #[serde(default)]
    all_owners: bool,
    /// When set, narrow to exactly this session id (still subject to the
    /// owner filter above) instead of newest-first selection — lets a
    /// caller that captured its own session id at spawn time finalize
    /// precisely that session, even when other sessions for the same agent
    /// are open concurrently in the same project (e.g. multiple terminal
    /// tabs each running Kiro CLI against one repo).
    #[serde(default)]
    session_id: Option<SessionId>,
    /// Also match the exact `session_id` when it already ended, instead of
    /// reporting "no open sessions". `finalize-session --reopen` passes
    /// this when re-closing a session that received new observations after
    /// its first end (e.g. an Antigravity conversation continued after a
    /// manual finalize); the server's normal session-end path then re-runs
    /// (page supersession, handoff, consolidation). Requires `session_id`:
    /// reopening is exact-id-only, never a bulk operation.
    #[serde(default)]
    include_ended: bool,
}

/// Wire shape for one open session in the `GET /admin/open-sessions`
/// response.
#[derive(Debug, Serialize)]
struct OpenSessionEntry {
    session_id: String,
    cwd: Option<String>,
}

/// Query string for `GET /admin/activity/by-client` — MCP tool-call
/// counts per client. Server-wide: MCP-only clients (the reason this
/// exists) are not reliably scoped to one project per call, and the
/// endpoint mirrors the buffer's own granularity.
///
/// `since_days = 0` means the whole history, mirroring
/// `/admin/sessions/by-agent`.
#[derive(Debug, Deserialize)]
struct ActivityByClientQuery {
    #[serde(default)]
    since_days: u32,
}

async fn handle_activity_by_client(
    State(state): State<Arc<AdminState>>,
    Query(query): Query<ActivityByClientQuery>,
) -> impl IntoResponse {
    let since_day = (query.since_days > 0).then(|| {
        jiff::Timestamp::now()
            .as_microsecond()
            .saturating_sub(i64::from(query.since_days).saturating_mul(US_PER_DAY))
            .div_euclid(US_PER_DAY)
    });
    match state.reader.client_activity_since(since_day).await {
        Ok(rows) => (
            StatusCode::OK,
            Json(
                serde_json::to_value(&rows)
                    .map(|list| serde_json::json!({ "by_client": list }))
                    .unwrap_or_else(|_| serde_json::json!({ "by_client": [] })),
            ),
        ),
        Err(e) => (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(serde_json::json!({ "error": e.to_string() })),
        ),
    }
}

#[derive(Debug, Deserialize)]
struct ProjectCoordinateQuery {
    workspace: String,
    project: String,
    identity: Option<String>,
    identity_source: Option<String>,
    identity_style: Option<String>,
}

async fn handle_project_coordinate(
    State(state): State<Arc<AdminState>>,
    Query(query): Query<ProjectCoordinateQuery>,
) -> impl IntoResponse {
    if query.workspace.trim().is_empty() || query.project.trim().is_empty() {
        return (
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "error": "workspace and project must be non-empty"
            })),
        );
    }
    let repository = match (query.identity.as_deref(), query.identity_source.as_deref()) {
        (None, None) => None,
        (Some(identity), Some(source)) => {
            match ai_memory_core::repository_identity::accept_wire_identity(identity, source) {
                Some(identity) => Some(identity),
                None => {
                    return (
                        StatusCode::BAD_REQUEST,
                        Json(serde_json::json!({ "error": "invalid repository identity" })),
                    );
                }
            }
        }
        _ => {
            return (
                StatusCode::BAD_REQUEST,
                Json(serde_json::json!({
                    "error": "identity and identity_source must be provided together"
                })),
            );
        }
    };
    let style = match query.identity_style.as_deref() {
        None => ai_memory_core::repository_identity::IdentityStyle::HostPath,
        Some(style) => {
            match ai_memory_core::repository_identity::IdentityStyle::from_str_opt(style) {
                Some(style) => style,
                None => {
                    return (
                        StatusCode::BAD_REQUEST,
                        Json(serde_json::json!({ "error": "invalid identity_style" })),
                    );
                }
            }
        }
    };
    match state
        .reader
        .diagnose_project_coordinate(query.workspace, query.project, repository, style)
        .await
    {
        Ok(diagnostic) => (
            StatusCode::OK,
            Json(serde_json::to_value(diagnostic).unwrap_or_else(|_| serde_json::json!({}))),
        ),
        Err(error) => internal_err(error.to_string()),
    }
}

/// Query string for `GET /admin/sessions/by-agent` — how many sessions each
/// agent CLI opened in one scope.
///
/// `since_days = 0` means "no lower bound": count the project's whole
/// history rather than an empty window, which is what a dashboard asking for
/// "all time" wants and what a `u32` cannot express as `None`.
#[derive(Debug, Deserialize)]
struct SessionsByAgentQuery {
    /// Workspace name (required).
    workspace: String,
    /// Project name (required).
    project: String,
    /// Inclusive lookback in days; zero means all history.
    #[serde(default)]
    since_days: u32,
    /// Report every operator's sessions instead of just the caller's. Same
    /// recovery switch the other scoped admin reads expose.
    #[serde(default)]
    all_owners: bool,
}

/// Microseconds in a day, for the `since_days` window.
const US_PER_DAY: i64 = 86_400_000_000;

async fn handle_sessions_by_agent(
    State(state): State<Arc<AdminState>>,
    actor_ext: Option<axum::Extension<ai_memory_core::ActorContext>>,
    Query(query): Query<SessionsByAgentQuery>,
) -> impl IntoResponse {
    let (ws, proj) = match lookup_ws_proj_no_create(&state, &query.workspace, &query.project).await
    {
        Ok(ids) => ids,
        Err(e) => return e,
    };
    let since_us = (query.since_days > 0).then(|| {
        jiff::Timestamp::now()
            .as_microsecond()
            .saturating_sub(i64::from(query.since_days).saturating_mul(US_PER_DAY))
    });
    let owner_filter = if query.all_owners {
        ai_memory_core::OwnerFilter::Any
    } else {
        ai_memory_core::OwnerFilter::for_actor_context(
            &actor_ext.map_or_else(ai_memory_core::ActorContext::anonymous, |ext| ext.0),
        )
    };
    let counts: ai_memory_store::StoreResult<Vec<ai_memory_store::AgentSessionCount>> = state
        .reader
        .session_counts_by_agent(ws, proj, owner_filter, since_us)
        .await;
    match counts {
        Ok(counts) => (
            StatusCode::OK,
            Json(
                serde_json::to_value(&counts)
                    .map(|list| serde_json::json!({ "by_agent": list }))
                    .unwrap_or_else(|_| serde_json::json!({ "by_agent": [] })),
            ),
        ),
        Err(e) => (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(serde_json::json!({ "error": e.to_string() })),
        ),
    }
}

/// Parse a kebab-case agent wire string into an [`AgentKind`].
fn parse_agent_kind(raw: &str) -> Option<AgentKind> {
    AgentKind::ALL.into_iter().find(|kind| kind.as_str() == raw)
}

async fn handle_open_sessions(
    State(state): State<Arc<AdminState>>,
    actor_ext: Option<axum::Extension<ai_memory_core::ActorContext>>,
    Query(query): Query<OpenSessionsQuery>,
) -> impl IntoResponse {
    if query.all && query.session_id.is_some() {
        return (
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "error": "all and session_id cannot be combined"
            })),
        );
    }
    if query.include_ended && query.session_id.is_none() {
        return (
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "error": "include_ended requires session_id"
            })),
        );
    }
    let Some(agent) = parse_agent_kind(&query.agent) else {
        return (
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "error": format!("unknown agent kind: {}", query.agent)
            })),
        );
    };
    let (ws, proj) = match lookup_ws_proj_no_create(&state, &query.workspace, &query.project).await
    {
        Ok(ids) => ids,
        Err(e) => return e,
    };
    let owner_filter = if query.all_owners {
        ai_memory_core::OwnerFilter::Any
    } else {
        ai_memory_core::OwnerFilter::for_actor_context(
            &actor_ext.map_or_else(ai_memory_core::ActorContext::anonymous, |ext| ext.0),
        )
    };
    let sessions = if let Some(session_id) = query.session_id {
        state
            .reader
            .open_session_for_scope_agent_by_id(
                ws,
                proj,
                agent,
                owner_filter,
                session_id,
                query.include_ended,
            )
            .await
            .map(|session| session.into_iter().collect())
    } else {
        let limit = if query.all { None } else { Some(1) };
        state
            .reader
            .open_sessions_for_scope_agent(ws, proj, agent, owner_filter, limit)
            .await
    };
    match sessions {
        Ok(sessions) => {
            let sessions: Vec<OpenSessionEntry> = sessions
                .into_iter()
                .map(|s| OpenSessionEntry {
                    session_id: s.session_id.to_string(),
                    cwd: s.cwd,
                })
                .collect();
            (
                StatusCode::OK,
                Json(
                    serde_json::to_value(&sessions)
                        .map(|list| serde_json::json!({ "sessions": list }))
                        .unwrap_or_else(|_| serde_json::json!({ "sessions": [] })),
                ),
            )
        }
        Err(e) => (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(serde_json::json!({ "error": e.to_string() })),
        ),
    }
}

// ---------------------------------------------------------------------
// search
// ---------------------------------------------------------------------

/// Query string for `GET /admin/search?q=…&limit=…`.
#[derive(Debug, Deserialize)]
struct SearchQuery {
    /// FTS5 query expression.
    q: String,
    /// Workspace name to search within. Must be provided together with `project`.
    #[serde(default)]
    workspace: Option<String>,
    /// Project name to search within. Must be provided together with `workspace`.
    #[serde(default)]
    project: Option<String>,
    /// Max number of hits to return. Capped at 100 server-side.
    #[serde(default = "default_search_limit")]
    limit: usize,
}

fn default_search_limit() -> usize {
    10
}

/// One hit of a cross-project `GET /admin/search` (no `workspace`/`project`).
///
/// The fields a global hit always carried (`id`, `path`, `title`, `snippet`,
/// `rank`) plus the workspace and project the page lives in, so a caller can
/// tell which repository each hit came from. A project-scoped search keeps
/// returning plain [`ai_memory_store::PageHit`]s.
#[derive(Debug, Serialize)]
struct GlobalSearchHit {
    id: ai_memory_core::PageId,
    path: ai_memory_core::PagePath,
    title: String,
    snippet: String,
    rank: f64,
    workspace: String,
    project: String,
}

impl From<ai_memory_store::PageHitWithMeta> for GlobalSearchHit {
    fn from(hit: ai_memory_store::PageHitWithMeta) -> Self {
        Self {
            id: hit.id,
            path: hit.path,
            title: hit.title,
            snippet: ai_memory_store::highlighted_snippet_html(&hit.snippet),
            rank: hit.rank,
            workspace: hit.workspace_name,
            project: hit.project_name,
        }
    }
}

async fn handle_search(
    State(state): State<Arc<AdminState>>,
    Query(query): Query<SearchQuery>,
) -> impl IntoResponse {
    let limit = query.limit.clamp(1, 100);
    let search_result = match (
        trimmed_opt(query.workspace.as_deref()),
        trimmed_opt(query.project.as_deref()),
    ) {
        (Some(workspace), Some(project)) => {
            match lookup_ws_proj_no_create(&state, workspace, project).await {
                Ok((ws, proj)) => state
                    .reader
                    .search_pages_for_project(ws, proj, query.q, limit, None)
                    .await
                    .and_then(|hits| Ok(serde_json::to_value(&hits)?)),
                Err(e) => return e,
            }
        }
        (Some(_), None) | (None, Some(_)) => {
            return (
                StatusCode::BAD_REQUEST,
                Json(serde_json::json!({
                    "error": "workspace and project must be provided together"
                })),
            );
        }
        // Cross-project: every hit names its repository. `OPERATOR` reads
        // every project because this route is root-only once the deployment
        // distinguishes operators (`require_root_for_multiuser_admin`).
        _ => state
            .reader
            .search_pages_with_meta(
                query.q,
                limit,
                None,
                OPERATOR,
                ai_memory_store::PageFilter::default(),
            )
            .await
            .and_then(|hits| {
                let hits: Vec<GlobalSearchHit> = hits.into_iter().map(Into::into).collect();
                Ok(serde_json::to_value(&hits)?)
            }),
    };
    match search_result {
        Ok(hits) => (StatusCode::OK, Json(hits)),
        Err(e) => (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(serde_json::json!({ "error": e.to_string() })),
        ),
    }
}

// ---------------------------------------------------------------------
// recent
// ---------------------------------------------------------------------

/// Query string for `GET /admin/recent?limit=…`.
#[derive(Debug, Deserialize)]
struct RecentQuery {
    /// Workspace name to list within. Must be provided together with `project`.
    #[serde(default)]
    workspace: Option<String>,
    /// Project name to list within. Must be provided together with `workspace`.
    #[serde(default)]
    project: Option<String>,
    /// Max number of pages to return. Capped at 100 server-side.
    #[serde(default = "default_search_limit")]
    limit: usize,
}

/// One hit of `GET /admin/recent`.
///
/// Recency has no FTS rank, so `updated_at` is RFC 3339 instead of the
/// store's reused `PageHit::rank` (updated_at microseconds as REAL). A
/// global listing also names the workspace and project; a scoped listing
/// omits those fields.
#[derive(Debug, Serialize)]
struct RecentHit {
    id: ai_memory_core::PageId,
    path: ai_memory_core::PagePath,
    title: String,
    snippet: String,
    updated_at: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    workspace: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    project: Option<String>,
}

fn iso_from_rank_us(rank: f64) -> String {
    // `recent_pages_*` store `updated_at` microseconds in `PageHit::rank`.
    // Unix µs in 2026 sit well below the 53-bit integer mantissa.
    #[allow(clippy::cast_possible_truncation, clippy::cast_precision_loss)]
    let us = rank.round() as i64;
    jiff::Timestamp::from_microsecond(us)
        .map(|ts| ts.to_string())
        .unwrap_or_default()
}

impl From<ai_memory_store::PageHit> for RecentHit {
    fn from(hit: ai_memory_store::PageHit) -> Self {
        Self {
            id: hit.id,
            path: hit.path,
            title: hit.title,
            snippet: hit.snippet,
            updated_at: iso_from_rank_us(hit.rank),
            workspace: None,
            project: None,
        }
    }
}

impl From<ai_memory_store::PageHitWithMeta> for RecentHit {
    fn from(hit: ai_memory_store::PageHitWithMeta) -> Self {
        Self {
            id: hit.id,
            path: hit.path,
            title: hit.title,
            snippet: hit.snippet,
            updated_at: iso_from_rank_us(hit.rank),
            workspace: Some(hit.workspace_name),
            project: Some(hit.project_name),
        }
    }
}

async fn handle_recent(
    State(state): State<Arc<AdminState>>,
    Query(query): Query<RecentQuery>,
) -> impl IntoResponse {
    let limit = query.limit.clamp(1, 100);
    let recent_result = match (
        trimmed_opt(query.workspace.as_deref()),
        trimmed_opt(query.project.as_deref()),
    ) {
        (Some(workspace), Some(project)) => {
            match lookup_ws_proj_no_create(&state, workspace, project).await {
                Ok((ws, proj)) => state
                    .reader
                    .recent_pages_for_project(ws, proj, limit)
                    .await
                    .and_then(|hits| {
                        let hits: Vec<RecentHit> = hits.into_iter().map(Into::into).collect();
                        Ok(serde_json::to_value(&hits)?)
                    }),
                Err(e) => return e,
            }
        }
        (Some(_), None) | (None, Some(_)) => {
            return (
                StatusCode::BAD_REQUEST,
                Json(serde_json::json!({
                    "error": "workspace and project must be provided together"
                })),
            );
        }
        // Cross-project: every hit names its repository. `OPERATOR` reads
        // every project because this route is root-only once the deployment
        // distinguishes operators (`require_root_for_multiuser_admin`).
        _ => state
            .reader
            .recent_pages_global(limit, OPERATOR)
            .await
            .and_then(|hits| {
                let hits: Vec<RecentHit> = hits.into_iter().map(Into::into).collect();
                Ok(serde_json::to_value(&hits)?)
            }),
    };
    match recent_result {
        Ok(hits) => (StatusCode::OK, Json(hits)),
        Err(e) => (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(serde_json::json!({ "error": e.to_string() })),
        ),
    }
}

// ---------------------------------------------------------------------
// read-page
// ---------------------------------------------------------------------

/// Query string for `GET /admin/read-page`.
///
/// Two modes:
/// - Path mode: `workspace` + `project` + `path` — direct lookup.
/// - Query mode: `workspace` + `project` + `q` — FTS5 search scoped to
///   the given project; fetches the top-ranking hit's full body.
#[derive(Debug, Deserialize)]
struct ReadPageQuery {
    /// Workspace name (required).
    workspace: String,
    /// Project name (required).
    project: String,
    /// Direct wiki path (e.g. `notes/foo.md`). Takes precedence over `q`.
    #[serde(default)]
    path: Option<String>,
    /// FTS5 query. Used when `path` is absent; fetches the top hit's full body.
    #[serde(default)]
    q: Option<String>,
}

/// Response body for `GET /admin/read-page`.
#[derive(Debug, Serialize)]
struct ReadPageResponse {
    path: String,
    workspace: String,
    project: String,
    title: Option<String>,
    body: String,
    frontmatter: serde_json::Value,
    #[serde(skip_serializing_if = "Option::is_none")]
    served_from: Option<&'static str>,
    /// Set when the page's `expires_at` TTL has passed: an exact-path read
    /// still serves the page, which search no longer lists.
    #[serde(skip_serializing_if = "std::ops::Not::not")]
    expired: bool,
}

async fn handle_read_page(
    State(state): State<Arc<AdminState>>,
    Query(query): Query<ReadPageQuery>,
) -> impl IntoResponse {
    let direct_path = if let Some(raw) = query.path {
        match ai_memory_core::PagePath::new(raw) {
            Ok(p) => Some(p),
            Err(e) => {
                return (
                    StatusCode::BAD_REQUEST,
                    Json(serde_json::json!({ "error": format!("invalid path: {e}") })),
                );
            }
        }
    } else {
        None
    };
    if direct_path.is_none() && query.q.is_none() {
        return (
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({ "error": "provide `path` or `q`" })),
        );
    }

    let (ws, proj) = match lookup_ws_proj_no_create(&state, &query.workspace, &query.project).await
    {
        Ok(ids) => ids,
        Err(e) => return e,
    };

    // Resolve the page path: direct `path` takes precedence over `q`.
    let page_path = if let Some(path) = direct_path {
        path
    } else if let Some(q) = query.q {
        let hits = match state
            .reader
            .search_pages_for_project(ws, proj, q.clone(), 1, None)
            .await
        {
            Ok(h) => h,
            Err(e) => return internal_err(e.to_string()),
        };
        match hits.into_iter().next() {
            Some(h) => h.path,
            None => {
                return (
                    StatusCode::NOT_FOUND,
                    Json(serde_json::json!({ "error": format!("no pages found for query {q:?}") })),
                );
            }
        }
    } else {
        return (
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({ "error": "provide `path` or `q`" })),
        );
    };

    // An expired page is still served (a read is not a search) but says so:
    // search and the listings leave it out, so this flag is how the caller
    // learns the page is only waiting for the forget sweep. Omitted while live.
    let expired = match state
        .reader
        .page_expired_by_ids(ws, proj, page_path.as_str())
        .await
    {
        Ok(expired) => expired.unwrap_or(false),
        Err(e) => return internal_err(e.to_string()),
    };

    match state.wiki.read_page(ws, proj, &page_path) {
        Ok(md) => {
            let title = md
                .frontmatter
                .get("title")
                .and_then(|v| v.as_str())
                .map(str::to_string);
            let resp = ReadPageResponse {
                path: page_path.to_string(),
                workspace: query.workspace,
                project: query.project,
                title,
                body: md.body,
                frontmatter: md.frontmatter,
                served_from: None,
                expired,
            };
            (
                StatusCode::OK,
                Json(serde_json::to_value(&resp).unwrap_or_else(|_| serde_json::json!({}))),
            )
        }
        // Only a missing markdown file can fall back to the DB copy. Other disk
        // errors belong to the source-of-truth file and must be surfaced.
        Err(disk_err) if is_missing_wiki_file(&disk_err) => match state
            .reader
            .page_body_by_ids(ws, proj, page_path.as_str())
            .await
        {
            Ok(Some(stored)) => {
                let frontmatter: serde_json::Value = serde_json::from_str(&stored.frontmatter_json)
                    .unwrap_or(serde_json::Value::Null);
                let title = frontmatter
                    .get("title")
                    .and_then(|v| v.as_str())
                    .map(str::to_string)
                    .or(Some(stored.title));
                let resp = ReadPageResponse {
                    path: page_path.to_string(),
                    workspace: query.workspace,
                    project: query.project,
                    title,
                    body: stored.body,
                    frontmatter,
                    served_from: Some("db-fallback"),
                    expired,
                };
                (
                    StatusCode::OK,
                    Json(serde_json::to_value(&resp).unwrap_or_else(|_| serde_json::json!({}))),
                )
            }
            Ok(None) => (
                StatusCode::NOT_FOUND,
                Json(serde_json::json!({ "error": disk_err.to_string() })),
            ),
            Err(e) => internal_err(e.to_string()),
        },
        Err(disk_err) => internal_err(disk_err.to_string()),
    }
}

// ---------------------------------------------------------------------
// Internal helpers
// ---------------------------------------------------------------------

/// Build a 500 response carrying the given message.
fn internal_err(msg: impl Into<String>) -> (StatusCode, Json<serde_json::Value>) {
    (
        StatusCode::INTERNAL_SERVER_ERROR,
        Json(serde_json::json!({ "error": msg.into() })),
    )
}

fn is_missing_wiki_file(err: &WikiError) -> bool {
    matches!(err, WikiError::Io(e) if e.kind() == std::io::ErrorKind::NotFound)
}

fn trimmed_opt(value: Option<&str>) -> Option<&str> {
    value.map(str::trim).filter(|s| !s.is_empty())
}

/// Who the admin surface resolves scopes as.
///
/// `/admin/*` is the operator's door: the router attaches
/// [`require_root_for_multiuser_admin`] as a `route_layer`, so on a multi-user
/// install only `AuthLevel::Root` reaches any handler below (a DB user gets
/// 403 — covered by the `admin_*_token` tests). Root authenticates from
/// configuration, not from a `users` row, so the auth middleware stamps no
/// `UserId` on the request and there is no per-repository grant to check.
///
/// This is therefore an assertion, not a forgotten argument: the operator is
/// authorized by the middleware above, at a coarser granularity than grants.
/// If a handler here ever needs to run as a named user, it must take the
/// `UserId` extension and pass it instead of this.
const OPERATOR: Option<ai_memory_core::UserId> = None;

/// Resolve workspace + project IDs, creating them if absent. Returns
/// either the IDs or a ready-to-return error response.
struct AdminWriteScope {
    scope: ai_memory_store::ResolvedScope,
    manifest_warning: Option<ai_memory_core::repository_identity::ManifestWarning>,
}

async fn create_ws_proj(
    state: &AdminState,
    workspace: &str,
    project: &str,
) -> Result<AdminWriteScope, (StatusCode, Json<serde_json::Value>)> {
    let resolved = ai_memory_store::create_explicit_scope(&state.writer, workspace, project)
        .await
        .map_err(scope_err)?;
    let manifest_warning = refresh_promoted_scope(state, &resolved).await;
    Ok(AdminWriteScope {
        scope: resolved.scope,
        manifest_warning,
    })
}

async fn refresh_promoted_scope(
    state: &AdminState,
    resolved: &ai_memory_store::ResolvedWriteScope,
) -> Option<ai_memory_core::repository_identity::ManifestWarning> {
    resolved.promoted_from.as_ref()?;
    match state
        .wiki
        .refresh_renamed_scope(resolved.scope.workspace_id, resolved.scope.project_id)
        .await
    {
        Ok(_) => None,
        Err(error) => {
            warn!(
                error = %error,
                workspace_id = %resolved.scope.workspace_id,
                project_id = %resolved.scope.project_id,
                "project name promotion committed; manifest refresh/checkpoint failed; startup backfill can repair"
            );
            Some(
                ai_memory_core::repository_identity::ManifestWarning::promotion_refresh_failed(
                    error,
                ),
            )
        }
    }
}

/// Look up workspace + project by name **without** auto-creating them.
/// Returns `(WorkspaceId, ProjectId)` on success, or a ready-to-return
/// 404/500 error response. Used by read, maintenance, and destructive
/// handlers where auto-creation would silently succeed on a typo.
async fn lookup_ws_proj_no_create(
    state: &AdminState,
    workspace: &str,
    project: &str,
) -> Result<(WorkspaceId, ProjectId), (StatusCode, Json<serde_json::Value>)> {
    lookup_existing_scope(&state.reader, workspace, project)
        .await
        .map(ai_memory_store::ResolvedScope::as_tuple)
        .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)
}

/// Resolve the `(workspace_id, project_id)` pair for an admin operation from
/// either a project name (the historic path) or a project id (the new
/// `#1208` path). Exactly one of `project_name` and `project_id` must be
/// `Some`; sending both or neither is a 400. When `project_id` is `Some`,
/// the workspace is resolved by name (still 404 if absent) and the project
/// is looked up by id within the workspace (404 on miss, so a foreign-scope
/// id is correctly refused). The bad-UUID case is a 400, mirroring how
/// `lookup_ws_proj_no_create` already maps unparseable names to 400.
///
/// Returns the project's stored name with the ids, so labels, admission
/// contexts and move destinations never fall back to the UUID: a failed name
/// read is a 500, not a guess.
async fn resolve_target_for_admin(
    state: &AdminState,
    workspace: &str,
    project_name: Option<&str>,
    project_id: Option<&str>,
) -> Result<(WorkspaceId, ProjectId, String), (StatusCode, Json<serde_json::Value>)> {
    let (ws_id, proj_id) =
        resolve_target_ids_for_admin(state, workspace, project_name, project_id).await?;
    match state.reader.project_name_by_id(ws_id, proj_id).await {
        Ok(Some(name)) => Ok((ws_id, proj_id, name)),
        Ok(None) => Err((
            StatusCode::NOT_FOUND,
            Json(serde_json::json!({ "error": "project not found in workspace" })),
        )),
        Err(e) => Err((
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(serde_json::json!({ "error": e.to_string() })),
        )),
    }
}

async fn resolve_target_ids_for_admin(
    state: &AdminState,
    workspace: &str,
    project_name: Option<&str>,
    project_id: Option<&str>,
) -> Result<(WorkspaceId, ProjectId), (StatusCode, Json<serde_json::Value>)> {
    match (project_name, project_id) {
        (Some(_), Some(_)) => Err((
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "error": "project and project_id are mutually exclusive"
            })),
        )),
        (None, None) => Err((
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "error": "either project or project_id is required"
            })),
        )),
        (Some(name), None) => lookup_ws_proj_no_create(state, workspace, name).await,
        (None, Some(id_str)) => {
            let parsed = match id_str.parse::<ProjectId>() {
                Ok(p) => p,
                Err(e) => {
                    return Err((
                        StatusCode::BAD_REQUEST,
                        Json(serde_json::json!({
                            "error": format!("invalid project id: {e}")
                        })),
                    ));
                }
            };
            let ws_id = match lookup_ws_no_create(state, workspace).await {
                Ok(ws) => ws,
                Err(e) => return Err(e),
            };
            match state.reader.project_name_by_id(ws_id, parsed).await {
                Ok(Some(_)) => Ok((ws_id, parsed)),
                Ok(None) => Err((
                    StatusCode::NOT_FOUND,
                    Json(serde_json::json!({
                        "error": "project not found in workspace"
                    })),
                )),
                Err(e) => Err((
                    StatusCode::INTERNAL_SERVER_ERROR,
                    Json(serde_json::json!({ "error": e.to_string() })),
                )),
            }
        }
    }
}

fn with_manifest_warning(
    (status, Json(mut body)): (StatusCode, Json<serde_json::Value>),
    warning: Option<&ai_memory_core::repository_identity::ManifestWarning>,
) -> (StatusCode, Json<serde_json::Value>) {
    if let (Some(warning), Some(object)) = (warning, body.as_object_mut()) {
        object.insert("manifest_warning".into(), serde_json::json!(warning));
    }
    (status, Json(body))
}

fn scope_err(err: ScopeResolutionError) -> (StatusCode, Json<serde_json::Value>) {
    let status = if err.is_bad_request() {
        StatusCode::BAD_REQUEST
    } else if err.is_forbidden() {
        StatusCode::FORBIDDEN
    } else if err.is_not_found() {
        StatusCode::NOT_FOUND
    } else {
        StatusCode::INTERNAL_SERVER_ERROR
    };
    (
        status,
        Json(serde_json::json!({ "error": err.to_string() })),
    )
}

fn skip_webhooks_for_admin_request(
    level_ext: Option<axum::Extension<ai_memory_core::AuthLevel>>,
    headers: &HeaderMap,
) -> Vec<String> {
    let level = level_ext
        .map(|axum::Extension(level)| level)
        .unwrap_or(ai_memory_core::AuthLevel::Anonymous);
    if level
        .authorize(Capability::SkipAdmissionChain, true)
        .is_ok()
    {
        crate::actor::skip_webhooks_from_headers(headers)
    } else {
        Vec::new()
    }
}

// ---------------------------------------------------------------------
// bootstrap
// ---------------------------------------------------------------------

async fn handle_bootstrap(
    State(state): State<Arc<AdminState>>,
    Json(req): Json<BootstrapRequest>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    // Dry-runs are READ-ONLY: no LLM call, no project creation, no
    // wiki write, no git commit. Early-return BEFORE any state-touching
    // call so a smoke-test (e.g. `--dry-run` from a tempdir) cannot
    // pollute the project list with throwaway names. Dry-runs can also
    // proceed in parallel with anything else — no mutex needed.
    if req.dry_run {
        return dry_run_outcome(
            req.sources,
            req.sources_collected,
            req.max_input_tokens,
            req.chunk_input_tokens,
        );
    }

    // Live runs from here on need LLM + workspace/project resolution.
    if state.llm.is_none() {
        return Err((
            StatusCode::SERVICE_UNAVAILABLE,
            Json(serde_json::json!({
                "error": "LLM provider not configured on server"
            })),
        ));
    }
    let target = create_ws_proj(&state, &req.workspace, &req.project).await?;
    let (ws, proj) = target.scope.as_tuple();

    // Serialise live bootstrap runs. Two parallel `process_sources`
    // calls would race the wiki's `commit_all` (libgit2 ops on the
    // same repo) and stack LLM cost unnecessarily. The wait is
    // operator-visible only in log lines; the request stays open
    // until the lock is acquired, then proceeds normally.
    if state.bootstrap_lock.try_lock().is_err() {
        info!(
            "another bootstrap is in progress; queueing — \
             this request waits for the active one to finish"
        );
    }
    let _bootstrap_guard = state.bootstrap_lock.lock().await;

    let llm = Arc::clone(
        state
            .llm
            .as_ref()
            .expect("llm is Some: checked above (non-dry-run without LLM returns 503)"),
    );

    let cfg = BootstrapConfig {
        // repo_path is unused by process_sources — the path field is
        // only consumed by collect_sources on the client side.
        repo_path: std::path::PathBuf::new(),
        workspace_id: ws,
        project_id: proj,
        max_input_tokens: req.max_input_tokens,
        chunk_input_tokens: req.chunk_input_tokens,
        sources_collected: req.sources_collected,
        // The individual include_* flags don't matter here: sources
        // are already collected; process_sources ignores them.
        include_git: true,
        include_readme: true,
        include_docs: true,
        include_code: true,
        since: None,
        dry_run: req.dry_run,
        force: req.force,
        resume: req.resume,
    };

    let bootstrap = Bootstrap {
        reader: state.reader.clone(),
        wiki: state.wiki.clone(),
        llm,
        writer: state.writer.clone(),
    };

    match bootstrap.process_sources(&cfg, req.sources).await {
        Ok(mut outcome) => {
            outcome.manifest_warning = target.manifest_warning.map(|warning| warning.to_string());
            Ok((
                StatusCode::OK,
                Json(serde_json::to_value(&outcome).unwrap_or_else(|_| serde_json::json!({}))),
            ))
        }
        Err(e) => Err(with_manifest_warning(
            bootstrap_error_response(e),
            target.manifest_warning.as_ref(),
        )),
    }
}

/// Build a dry-run [`BootstrapOutcome`] without an LLM by applying the
/// same budget-pruning logic that `Bootstrap::process_sources` would use.
/// Map a [`BootstrapError`] to the appropriate HTTP status code.
///
/// - `NoSources` / `AlreadyBootstrapped` → 422 (validation failures).
/// - `Llm` → 502 (upstream provider failure).
/// - Everything else → 500 (unexpected server-side error).
fn bootstrap_error_response(
    e: ai_memory_consolidate::BootstrapError,
) -> (StatusCode, Json<serde_json::Value>) {
    use ai_memory_consolidate::BootstrapError;
    let status = match &e {
        BootstrapError::NoSources | BootstrapError::AlreadyBootstrapped => {
            StatusCode::UNPROCESSABLE_ENTITY
        }
        BootstrapError::Llm(_) => StatusCode::BAD_GATEWAY,
        _ => StatusCode::INTERNAL_SERVER_ERROR,
    };
    log_server_error(status, "bootstrap", &e);
    (status, Json(serde_json::json!({ "error": e.to_string() })))
}

/// Record a failure the server owns.
///
/// A 5xx says the request was fine and *we* could not serve it, so the reason
/// belongs in the server's log: the response body reaches one client once and
/// is gone when its process exits, which is how an upstream provider 404
/// managed to fail every bootstrap while the log showed only the run starting
/// (#692). A 4xx stays quiet — the caller was told, and the caller was at
/// fault.
fn log_server_error(status: StatusCode, operation: &str, error: &dyn std::fmt::Display) {
    if status.is_server_error() {
        warn!(%status, operation, %error, "admin request failed");
    }
}

/// Build a dry-run [`BootstrapOutcome`] without an LLM by applying the
/// same budget-pruning logic that `Bootstrap::process_sources` would use.
fn dry_run_outcome(
    sources: Vec<BootstrapSource>,
    sources_collected: Option<usize>,
    max_input_tokens: usize,
    chunk_input_tokens: usize,
) -> Result<(StatusCode, Json<serde_json::Value>), (StatusCode, Json<serde_json::Value>)> {
    use ai_memory_consolidate::BootstrapError;
    if sources.is_empty() {
        return Err((
            StatusCode::UNPROCESSABLE_ENTITY,
            Json(serde_json::json!({
                "error": BootstrapError::NoSources.to_string()
            })),
        ));
    }
    let incoming = sources.len();
    let (kept, _dropped, total) = prune_sources_to_budget(sources, max_input_tokens);
    if kept.is_empty() {
        return Err((
            StatusCode::UNPROCESSABLE_ENTITY,
            Json(serde_json::json!({
                "error": BootstrapError::NoSources.to_string()
            })),
        ));
    }
    let collected = sources_collected.unwrap_or(incoming);
    let sources_sent = kept.len();
    let sources_dropped = collected.saturating_sub(sources_sent);
    let counts = SourceCounts::from_sources(&kept);
    let chunk_budget =
        ai_memory_consolidate::effective_chunk_budget(chunk_input_tokens, max_input_tokens);
    let llm_chunks = ai_memory_consolidate::plan_bootstrap_chunks(kept.clone(), chunk_budget).len();
    let outcome = BootstrapOutcome {
        sources_collected: collected,
        sources_sent,
        sources_dropped,
        sources_by_kind: counts,
        estimated_input_tokens: total,
        pages_written: Vec::new(),
        rationale: "(dry-run; LLM not invoked)".to_string(),
        dry_run: true,
        llm_chunks,
        manifest_warning: None,
    };
    Ok((
        StatusCode::OK,
        Json(serde_json::to_value(&outcome).unwrap_or_else(|_| serde_json::json!({}))),
    ))
}

// ---------------------------------------------------------------------
// auto-improve reviewer/stager
// ---------------------------------------------------------------------

async fn handle_auto_improve(
    State(state): State<Arc<AdminState>>,
    actor_ext: Option<axum::Extension<ai_memory_core::ActorContext>>,
    author_ext: Option<axum::Extension<ai_memory_core::UserId>>,
    level_ext: Option<axum::Extension<ai_memory_core::AuthLevel>>,
    headers: HeaderMap,
    Json(req): Json<AutoImproveRequest>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    if req.eval.is_some() {
        return Err((
            StatusCode::UNPROCESSABLE_ENTITY,
            Json(serde_json::json!({
                "error": "auto-improve eval request field was removed; configure [auto_improve.eval] on the server"
            })),
        ));
    }
    if req.dry_run.is_some() || req.stage.is_some() || req.mode.is_some() {
        return Err((
            StatusCode::UNPROCESSABLE_ENTITY,
            Json(serde_json::json!({
                "error": "auto-improve dry_run/stage/mode request fields were removed; set [auto_improve].require_approval = true for manual review"
            })),
        ));
    }
    let (ws, proj) = lookup_ws_proj_no_create(&state, &req.workspace, &req.project).await?;
    let Some(llm) = state.llm.as_ref().cloned() else {
        return Err((
            StatusCode::SERVICE_UNAVAILABLE,
            Json(serde_json::json!({
                "error": "LLM provider not configured on server"
            })),
        ));
    };

    let cfg = AutoImproveReviewConfig {
        min_observations: req.min_observations,
        min_session_duration_secs: req.min_session_duration_secs,
        min_confidence: req.min_confidence,
        max_input_tokens: req.max_input_tokens,
        max_proposals_per_run: req.max_proposals_per_run,
        include_raw_fallback: req.include_raw_fallback,
        proposal_actor: req.proposal_actor.clone(),
        pending_path: req.pending_path.clone(),
        max_patchable_pages: req.max_patchable_pages,
        // The admin request body does not expose this, so the reviewer uses the
        // server-configured `[auto_improve] patchable_page_prefixes` (which
        // itself defaults to the historical `_rules/`/`procedures/`) rather than
        // ignoring the operator's config on the admin-triggered path (#834).
        patchable_page_prefixes: state
            .auto_improve_review_config
            .patchable_page_prefixes
            .clone(),
        max_patchable_body_chars: req.max_patchable_body_chars,
        max_edits_per_proposal: req.max_edits_per_proposal,
        max_edit_content_chars: req.max_edit_content_chars,
        max_changed_chars_per_proposal: req.max_changed_chars_per_proposal,
        max_patch_edits_per_run: req.max_patch_edits_per_run,
        max_rejection_context: req.max_rejection_context,
        rejection_context_days: req.rejection_context_days,
        max_final_body_chars: req.max_final_body_chars,
        max_rule_page_tokens: req.max_rule_page_tokens,
        max_procedure_page_tokens: req.max_procedure_page_tokens,
        eval: state.auto_improve_review_config.eval.clone(),
    };

    let report =
        run_auto_improve_review(&state.reader, &*llm, ws, proj, req.session_id, cfg.clone())
            .await
            .map_err(auto_improve_error_response)?;
    // Whose suggestion this is. It scopes the one-pending-per-target rule
    // (V42), and is taken from the authenticated actor's qualified identity
    // key rather than a `users` row, because most identified operators on a
    // shared server are named by an authenticating proxy and never get one.
    //
    // Only where operators are actually told apart, though: on a
    // single-operator server this call would otherwise stage into bucket
    // `user:<root_username>` while the scheduler and the report handlers stage
    // into the unattributed one, leaving two proposals pending for the same
    // page — the collision V42 promises cannot happen.
    //
    // Both halves go through the shared accessors — `identity_key` for "which
    // human is this", `owner_identity` for "does this deployment name them" —
    // rather than re-deriving either here. Its `memory_auto_improve` sibling
    // stages into the same V42 bucket, and a bucket computed two ways is a
    // bucket that eventually disagrees with itself.
    let staging_owner = ai_memory_core::owner_identity(
        actor_ext
            .as_ref()
            .and_then(|axum::Extension(actor)| actor.identity_key())
            .as_ref(),
        state
            .reader
            .distinguishes_operators(state.trusted_proxy_identity)
            .await
            .map_err(|e| internal_err(e.to_string()))?,
    );
    let proposals = auto_improve_new_proposals(&state, ws, proj, &report).await?;
    let staged = stage_auto_improve_report(
        &state,
        AutoImproveStagingScope {
            ws,
            proj,
            session_id: req.session_id,
            cfg: &cfg,
            staging_owner,
        },
        &report,
        proposals,
    )
    .await?;
    let actor = actor_ext
        .map(|axum::Extension(actor)| actor)
        .unwrap_or_else(ai_memory_core::ActorContext::anonymous);
    let author_id = author_ext.map(|axum::Extension(author_id)| author_id);
    let skip_webhooks = skip_webhooks_for_admin_request(level_ext, &headers);
    let outcomes = finalize_auto_improve_proposals(
        &state,
        &staged,
        AutoImproveFinalizeContext {
            workspace_id: ws,
            project_id: proj,
            require_approval: state.auto_improve_require_approval,
            actor,
            author_id,
            admission_ctx: Some(AdmissionContext {
                op: AdmissionOp::WritePage,
                skip_webhooks,
                ..AdmissionContext::default()
            }),
        },
    )
    .await?;
    Ok((
        StatusCode::OK,
        Json(
            serde_json::to_value(AutoImproveStageResponse {
                run_id: staged.run_id.to_string(),
                approval_required: state.auto_improve_require_approval,
                approval_policy: if state.auto_improve_require_approval {
                    "manual".into()
                } else {
                    "auto_approve".into()
                },
                session_id: req.session_id.to_string(),
                summary: report.summary,
                warnings: report.warnings,
                rejected_candidates_count: report.rejected_candidates.len(),
                proposals: outcomes,
                // Store-level collisions the reviewer's run never staged.
                // Dropped silently, a run reporting N-1 proposals has nothing
                // saying the Nth ever existed.
                skipped: staged.skipped,
            })
            .unwrap_or_else(|_| serde_json::json!({})),
        ),
    ))
}

fn auto_improve_auto_approve_actor(
    mut actor: ai_memory_core::ActorContext,
) -> ai_memory_core::ActorContext {
    actor.agent = Some("auto_improve_auto_approve".into());
    actor
}

struct AutoImproveFinalizeContext {
    workspace_id: WorkspaceId,
    project_id: ProjectId,
    require_approval: bool,
    actor: ai_memory_core::ActorContext,
    author_id: Option<ai_memory_core::UserId>,
    admission_ctx: Option<AdmissionContext>,
}

async fn finalize_auto_improve_proposals(
    state: &AdminState,
    staged: &StagedAutoImproveData,
    ctx: AutoImproveFinalizeContext,
) -> Result<Vec<AutoImproveProposalOutcome>, (StatusCode, Json<serde_json::Value>)> {
    let mut outcomes = Vec::with_capacity(staged.proposal_ids.len());
    for (proposal_id, sidecar_path) in staged.proposal_ids.iter().zip(staged.sidecar_paths.iter()) {
        if ctx.require_approval {
            outcomes.push(AutoImproveProposalOutcome {
                id: proposal_id.to_string(),
                sidecar_path: sidecar_path.clone(),
                status: "pending".into(),
                page_id: None,
            });
            continue;
        }

        let approval_actor = auto_improve_auto_approve_actor(ctx.actor.clone());
        match state
            .wiki
            .approve_auto_improve_proposal(
                ctx.workspace_id,
                ctx.project_id,
                *proposal_id,
                approval_actor,
                ctx.author_id,
                ctx.admission_ctx.clone(),
            )
            .await
        {
            Ok(ApproveAutoImproveProposalResult::Approved { page_id }) => {
                outcomes.push(AutoImproveProposalOutcome {
                    id: proposal_id.to_string(),
                    sidecar_path: sidecar_path.clone(),
                    status: "approved".into(),
                    page_id: Some(page_id.to_string()),
                });
            }
            Ok(ApproveAutoImproveProposalResult::Conflict) => {
                outcomes.push(AutoImproveProposalOutcome {
                    id: proposal_id.to_string(),
                    sidecar_path: sidecar_path.clone(),
                    status: "conflict".into(),
                    page_id: None,
                });
            }
            Err(e) => return Err(internal_err(e.to_string())),
        }
    }
    Ok(outcomes)
}

async fn auto_improve_new_proposals(
    state: &AdminState,
    ws: WorkspaceId,
    proj: ProjectId,
    report: &ai_memory_consolidate::AutoImproveReport,
) -> Result<Vec<NewAutoImproveProposal>, (StatusCode, Json<serde_json::Value>)> {
    let mut proposals = Vec::with_capacity(report.proposals.len());
    for p in &report.proposals {
        let path = PagePath::new(p.path.clone()).map_err(|e| {
            (
                StatusCode::UNPROCESSABLE_ENTITY,
                Json(serde_json::json!({ "error": format!("invalid proposal path: {e}") })),
            )
        })?;
        let target_exists = state
            .reader
            .page_body_by_ids(ws, proj, path.as_str())
            .await
            .map_err(|e| internal_err(e.to_string()))?
            .is_some();
        let operation = if p.edit_mode == "patch"
            || (target_exists && path.as_str() == "_slots/current-focus.md")
        {
            AutoImproveProposalOperation::Update
        } else {
            AutoImproveProposalOperation::Create
        };
        let expected_base_body_sha256 = p
            .expected_base_body_sha256
            .as_deref()
            .map(hex_to_sha256)
            .transpose()
            .map_err(|e| internal_err(format!("invalid expected_base_body_sha256: {e}")))?;
        proposals.push(NewAutoImproveProposal {
            operation,
            target_path: path,
            kind: p.kind.clone(),
            title: p.title.clone(),
            confidence: f64::from(p.confidence),
            rationale: p.rationale.clone(),
            evidence_json: report
                .proposal_evidence_json(p)
                .map_err(|e| internal_err(e.to_string()))?,
            body_markdown: p.body_markdown.clone(),
            artifact_sha256: None,
            edit_mode: Some(p.edit_mode.clone()),
            patch_json: serde_json::to_value(&p.edits).ok(),
            expected_base_body_sha256,
        });
    }
    Ok(proposals)
}

struct StagedAutoImproveData {
    run_id: ai_memory_core::AutoImproveRunId,
    proposal_ids: Vec<AutoImproveProposalId>,
    sidecar_paths: Vec<String>,
    /// Proposals the store refused to stage. Dropping these here would hand the
    /// operator a run reporting N-1 proposals with nothing saying the Nth
    /// existed — the silent drop the per-proposal skip was meant to end.
    skipped: Vec<SkippedProposal>,
}

/// Everything `stage_auto_improve_report` needs about WHO and WHERE, bundled so
/// the helper keeps a readable arity.
struct AutoImproveStagingScope<'a> {
    ws: WorkspaceId,
    proj: ProjectId,
    session_id: SessionId,
    cfg: &'a AutoImproveReviewConfig,
    /// Typed operator that staged the run; also scopes the
    /// one-pending-per-target rule.
    staging_owner: Option<ai_memory_core::IdentityKey>,
}

async fn stage_auto_improve_report(
    state: &AdminState,
    scope: AutoImproveStagingScope<'_>,
    report: &ai_memory_consolidate::AutoImproveReport,
    proposals: Vec<NewAutoImproveProposal>,
) -> Result<StagedAutoImproveData, (StatusCode, Json<serde_json::Value>)> {
    let AutoImproveStagingScope {
        ws,
        proj,
        session_id,
        cfg,
        staging_owner,
    } = scope;
    let staged = state
        .writer
        .stage_auto_improve_run_for_owner(
            StageAutoImproveRun {
                workspace_id: ws,
                project_id: proj,
                session_id: Some(session_id),
                provider: Some(report.provider.clone()),
                model: Some(report.model.clone()),
                summary: Some(report.summary.clone()),
                warnings_json: serde_json::to_value(&report.warnings)
                    .unwrap_or_else(|_| serde_json::json!([])),
                rejected_candidates_json: serde_json::to_value(&report.rejected_candidates)
                    .unwrap_or_else(|_| serde_json::json!([])),
                config_json: serde_json::json!({
                    "min_observations": cfg.min_observations,
                    "min_session_duration_secs": cfg.min_session_duration_secs,
                    "min_confidence": cfg.min_confidence,
                    "max_input_tokens": cfg.max_input_tokens,
                    "max_proposals_per_run": cfg.max_proposals_per_run,
                    "include_raw_fallback": cfg.include_raw_fallback,
                    "max_patchable_pages": cfg.max_patchable_pages,
                    "max_patchable_body_chars": cfg.max_patchable_body_chars,
                    "max_edits_per_proposal": cfg.max_edits_per_proposal,
                    "max_edit_content_chars": cfg.max_edit_content_chars,
                    "max_changed_chars_per_proposal": cfg.max_changed_chars_per_proposal,
                    "max_patch_edits_per_run": cfg.max_patch_edits_per_run,
                    "max_rejection_context": cfg.max_rejection_context,
                    "rejection_context_days": cfg.rejection_context_days,
                    "max_final_body_chars": cfg.max_final_body_chars,
                    "max_rule_page_tokens": cfg.max_rule_page_tokens,
                    "max_procedure_page_tokens": cfg.max_procedure_page_tokens,
                    "eval": cfg.eval,
                    "eval_results": report.eval_results(),
                }),
                proposal_actor: ai_memory_core::ActorContext {
                    agent: Some(cfg.proposal_actor.clone()),
                    ..ai_memory_core::ActorContext::default()
                },
                proposals,
            },
            staging_owner,
        )
        .await
        .map_err(|e| internal_err(e.to_string()))?;
    let sidecar_paths = write_auto_improve_sidecars(state, ws, proj, &staged.proposal_ids).await?;
    Ok(StagedAutoImproveData {
        run_id: staged.run_id,
        proposal_ids: staged.proposal_ids,
        sidecar_paths,
        skipped: staged.skipped,
    })
}

async fn target_operation_for_page(
    state: &AdminState,
    ws: WorkspaceId,
    proj: ProjectId,
    target: &PagePath,
) -> Result<AutoImproveProposalOperation, (StatusCode, Json<serde_json::Value>)> {
    if state
        .reader
        .page_body_by_ids(ws, proj, target.as_str())
        .await
        .map_err(|e| internal_err(e.to_string()))?
        .is_some()
    {
        Ok(AutoImproveProposalOperation::Update)
    } else {
        Ok(AutoImproveProposalOperation::Create)
    }
}

async fn write_auto_improve_sidecars(
    state: &AdminState,
    ws: WorkspaceId,
    proj: ProjectId,
    proposal_ids: &[AutoImproveProposalId],
) -> Result<Vec<String>, (StatusCode, Json<serde_json::Value>)> {
    let mut sidecar_paths = Vec::with_capacity(proposal_ids.len());
    for id in proposal_ids {
        let path = state
            .wiki
            .write_auto_improve_sidecar(ws, proj, *id)
            .await
            .map_err(|e| internal_err(e.to_string()))?;
        sidecar_paths.push(path.display().to_string());
    }
    Ok(sidecar_paths)
}

fn auto_improve_error_response(
    e: ai_memory_consolidate::AutoImproveError,
) -> (StatusCode, Json<serde_json::Value>) {
    use ai_memory_consolidate::AutoImproveError;
    let status = match &e {
        AutoImproveError::SessionNotFound(_) => StatusCode::NOT_FOUND,
        AutoImproveError::SessionOutOfScope { .. } => StatusCode::UNPROCESSABLE_ENTITY,
        AutoImproveError::Llm(_) => StatusCode::BAD_GATEWAY,
        AutoImproveError::Eval(_) => StatusCode::BAD_GATEWAY,
        AutoImproveError::Memory(_) => StatusCode::BAD_REQUEST,
        AutoImproveError::Store(_) => StatusCode::INTERNAL_SERVER_ERROR,
    };
    log_server_error(status, "auto-improve", &e);
    (status, Json(serde_json::json!({ "error": e.to_string() })))
}

// ---------------------------------------------------------------------
// auto-improve telemetry report
// ---------------------------------------------------------------------

async fn handle_auto_improve_report(
    State(state): State<Arc<AdminState>>,
    Json(req): Json<AutoImproveTelemetryReportRequest>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    let (ws, proj) = lookup_ws_proj_no_create(&state, &req.workspace, &req.project).await?;
    let params = AutoImproveTelemetryParams {
        since_days: req.since_days,
        top_limit: req.limit.clamp(1, 100),
    };
    let report = run_auto_improve_telemetry_report(
        &state.reader,
        ws,
        proj,
        &req.workspace,
        &req.project,
        params.clone(),
    )
    .await
    .map_err(|e| internal_err(e.to_string()))?;
    if req.stage {
        let body_markdown = render_auto_improve_telemetry_report_markdown(&report);
        let target_path = auto_improve_report_target_path();
        let target = PagePath::new(target_path).map_err(|e| {
            (
                StatusCode::UNPROCESSABLE_ENTITY,
                Json(serde_json::json!({ "error": format!("invalid auto-improve report target path: {e}") })),
            )
        })?;
        let operation = target_operation_for_page(&state, ws, proj, &target).await?;
        let staged = state
            .writer
            .stage_auto_improve_run_for_owner(
                StageAutoImproveRun {
                workspace_id: ws,
                project_id: proj,
                session_id: None,
                provider: None,
                model: None,
                summary: Some(format!("Auto-improve telemetry report: {}", report.summary)),
                warnings_json: serde_json::json!([]),
                rejected_candidates_json: serde_json::json!([]),
                config_json: serde_json::json!({
                    "mode": "stage",
                    "auto_improve_report": true,
                    "params": params,
                }),
                proposal_actor: ai_memory_core::ActorContext {
                    agent: Some("auto_improve_report".into()),
                    ..ai_memory_core::ActorContext::default()
                },
                proposals: vec![NewAutoImproveProposal {
                    operation,
                    target_path: target,
                    kind: "auto_improve_report".into(),
                    title: "Auto-improve Telemetry Report".into(),
                    confidence: 1.0,
                    rationale: "Telemetry report only; approval writes the report page and performs no learning-memory changes.".into(),
                    evidence_json: serde_json::json!({
                        "summary": report.summary.clone(),
                        "findings": report.findings.clone(),
                        "params": report.params.clone(),
                    }),
                    body_markdown,
                    artifact_sha256: None,
                    edit_mode: None,
                    patch_json: None,
                    expected_base_body_sha256: None,
                }],
                },
                None,
            )
            .await
            .map_err(|e| internal_err(e.to_string()))?;
        let sidecar_paths =
            write_auto_improve_sidecars(&state, ws, proj, &staged.proposal_ids).await?;
        return Ok((
            StatusCode::OK,
            Json(
                serde_json::to_value(AutoImproveTelemetryReportStageResponse {
                    run_id: staged.run_id.to_string(),
                    proposal_ids: staged
                        .proposal_ids
                        .iter()
                        .map(ToString::to_string)
                        .collect(),
                    sidecar_paths,
                    skipped: staged.skipped,
                    report,
                })
                .unwrap_or_else(|_| serde_json::json!({})),
            ),
        ));
    }
    Ok((
        StatusCode::OK,
        Json(serde_json::to_value(&report).unwrap_or_else(|_| serde_json::json!({}))),
    ))
}

async fn handle_curator(
    State(state): State<Arc<AdminState>>,
    axum::Extension(tuning): axum::Extension<SweepTuning>,
    Json(req): Json<CuratorRequest>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    let mode = req.mode.as_deref().map(str::trim).filter(|s| !s.is_empty());
    let wants_stage = req.stage || matches!(mode, Some("stage"));
    let explicit_dry_run = req.dry_run || matches!(mode, Some("dry_run" | "dry-run"));
    if wants_stage && explicit_dry_run {
        return Err((
            StatusCode::UNPROCESSABLE_ENTITY,
            Json(serde_json::json!({ "error": "choose either dry_run or stage, not both" })),
        ));
    }
    if let Some(other) = mode
        && !matches!(other, "stage" | "dry_run" | "dry-run")
    {
        return Err((
            StatusCode::UNPROCESSABLE_ENTITY,
            Json(serde_json::json!({ "error": format!("unknown curator mode '{other}'") })),
        ));
    }
    let wants_dry_run = explicit_dry_run || !wants_stage;

    let (ws, proj) = lookup_ws_proj_no_create(&state, &req.workspace, &req.project).await?;
    let params = CuratorParams::default();
    let mut report = run_curator_report_with_breadth(
        &state.reader,
        ws,
        proj,
        &req.workspace,
        &req.project,
        params.clone(),
        tuning.breadth_weight,
    )
    .await
    .map_err(|e| internal_err(e.to_string()))?;
    if wants_dry_run {
        report.dry_run = true;
        return Ok((
            StatusCode::OK,
            Json(serde_json::to_value(&report).unwrap_or_else(|_| serde_json::json!({}))),
        ));
    }

    report.dry_run = false;
    let body_markdown = render_curator_report_markdown(&report);
    let target_path = curator_target_path();
    let target = PagePath::new(target_path).map_err(|e| {
        (
            StatusCode::UNPROCESSABLE_ENTITY,
            Json(serde_json::json!({ "error": format!("invalid curator target path: {e}") })),
        )
    })?;
    let operation = target_operation_for_page(&state, ws, proj, &target).await?;

    let staged = state
            .writer
            .stage_auto_improve_run_for_owner(
                StageAutoImproveRun {
                    workspace_id: ws,
                    project_id: proj,
                    session_id: None,
                    provider: None,
                    model: None,
                    summary: Some(report.summary.clone()),
                    warnings_json: serde_json::json!([]),
                    rejected_candidates_json: serde_json::json!([]),
                    config_json: serde_json::json!({
                        "mode": "stage",
                        "curator": true,
                        "params": params,
                    }),
                    proposal_actor: ai_memory_core::ActorContext {
                        agent: Some("curator".into()),
                        ..ai_memory_core::ActorContext::default()
                    },
                    proposals: vec![NewAutoImproveProposal {
                        operation,
                        target_path: target,
                        kind: "curator_report".into(),
                        title: "Curator Report".into(),
                        confidence: 1.0,
                        rationale: "Rule-based curator report only; approval writes the report page and performs no maintenance actions.".into(),
                        evidence_json: serde_json::json!({
                            "summary": report.summary.clone(),
                            "findings": report.findings.clone(),
                        }),
                        body_markdown,
                        artifact_sha256: None,
                        edit_mode: None,
                        patch_json: None,
                        expected_base_body_sha256: None,
                    }],
                },
            None,
        )
        .await
        .map_err(|e| internal_err(e.to_string()))?;
    let sidecar_paths = write_auto_improve_sidecars(&state, ws, proj, &staged.proposal_ids).await?;
    Ok((
        StatusCode::OK,
        Json(
            serde_json::to_value(CuratorStageResponse {
                run_id: staged.run_id.to_string(),
                proposal_ids: staged
                    .proposal_ids
                    .iter()
                    .map(ToString::to_string)
                    .collect(),
                sidecar_paths,
                skipped: staged.skipped,
                report,
            })
            .unwrap_or_else(|_| serde_json::json!({})),
        ),
    ))
}

fn curator_target_path() -> String {
    let now = jiff::Timestamp::now().to_string();
    let date = now.get(0..10).unwrap_or("latest");
    format!("notes/curator-{date}.md")
}

fn auto_improve_report_target_path() -> String {
    let stamp = jiff::Timestamp::now().as_microsecond();
    format!("notes/auto-improve-report-{stamp}.md")
}

/// List open handoffs so an operator can cancel one (#513).
///
/// `memory_handoff_cancel` requires an exact id and nothing exposed one, so a
/// backlog showed up as a count in `status` and could not be addressed.
/// Read-only, oldest first, and content-free: identity, provenance and age,
/// never the handoff body.
async fn handle_open_handoffs_list(
    State(state): State<Arc<AdminState>>,
    Query(query): Query<OpenHandoffsQuery>,
) -> impl IntoResponse {
    let (ws, proj) = match lookup_ws_proj_no_create(&state, &query.workspace, &query.project).await
    {
        Ok(ids) => ids,
        Err(e) => return e,
    };
    let limit = query.limit.clamp(1, 500);
    match state
        .reader
        .open_handoffs_for_project(ws, proj, limit)
        .await
    {
        Ok(handoffs) => (
            StatusCode::OK,
            Json(serde_json::json!({ "handoffs": handoffs })),
        ),
        Err(e) => (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(serde_json::json!({ "error": e.to_string() })),
        ),
    }
}

/// `POST /admin/handoffs/expire` request body.
#[derive(Deserialize)]
struct ExpireHandoffsRequest {
    workspace: String,
    project: String,
    /// Mandatory. Without `confirm: true` the server returns 400.
    #[serde(default)]
    confirm: bool,
    /// Only expire handoffs at least this many days old. Omitted clears the
    /// whole open backlog for the scope.
    #[serde(default)]
    older_than_days: Option<u32>,
}

/// `POST /admin/handoffs/expire` — clear the open handoff backlog for one
/// scope.
///
/// Unlike the automatic sweep this does not spare manual or
/// different-directory handoffs. Those exemptions are what the leftover
/// backlog is made of, so honouring them here would expire nothing. It is a
/// state change rather than a delete: the summary and provenance survive and
/// the handoff simply stops being consumable (#513).
async fn handle_expire_handoffs(
    State(state): State<Arc<AdminState>>,
    actor_ext: Option<axum::Extension<ai_memory_core::ActorContext>>,
    author_ext: Option<axum::Extension<ai_memory_core::UserId>>,
    Json(req): Json<ExpireHandoffsRequest>,
) -> impl IntoResponse {
    if !req.confirm {
        return (
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "error": "expiring the handoff backlog requires confirm=true"
            })),
        );
    }
    let (ws, proj) = match lookup_ws_proj_no_create(&state, &req.workspace, &req.project).await {
        Ok(ids) => ids,
        Err(e) => return e,
    };

    // Same owner scoping as cancel: a caller clears their own and shared
    // batons, never somebody else's.
    let actor = actor_ext
        .map(|axum::Extension(a)| a)
        .unwrap_or_else(ai_memory_core::ActorContext::anonymous);
    let owner_filter = ai_memory_core::OwnerFilter::for_actor_context(&actor);
    let author_id = author_ext.map(|axum::Extension(u)| u);

    let older_than_us = req.older_than_days.map(|days| {
        jiff::Timestamp::now().as_microsecond() - i64::from(days) * 24 * 60 * 60 * 1_000_000
    });

    match state
        .writer
        .expire_open_handoffs(ws, proj, owner_filter, older_than_us, author_id)
        .await
    {
        Ok(expired) => (
            StatusCode::OK,
            Json(serde_json::json!({
                "expired": expired,
                "workspace": req.workspace,
                "project": req.project,
            })),
        ),
        Err(e) => internal_err(e.to_string()),
    }
}

/// List one side of a project's cross-project mailbox (V64): `box=inbox`
/// (default) is mail addressed to it, `box=outbox` is mail it has sent and
/// can still cancel. Oldest first, capped at `limit`. See
/// `docs/agent-messaging.md`.
async fn handle_list_messages(
    State(state): State<Arc<AdminState>>,
    Query(query): Query<ListMessagesQuery>,
) -> impl IntoResponse {
    let (ws, proj) = match lookup_ws_proj_no_create(&state, &query.workspace, &query.project).await
    {
        Ok(ids) => ids,
        Err(e) => return e,
    };
    let mailbox = match query.mailbox.as_str() {
        "inbox" => ai_memory_core::MessageBox::Inbox,
        "outbox" => ai_memory_core::MessageBox::Outbox,
        other => {
            return (
                StatusCode::BAD_REQUEST,
                Json(serde_json::json!({
                    "error": format!("box must be \"inbox\" or \"outbox\", got {other:?}")
                })),
            );
        }
    };
    let limit = query.limit.clamp(1, 200);
    match state.reader.list_messages(ws, proj, mailbox, limit).await {
        Ok(messages) => (
            StatusCode::OK,
            Json(serde_json::json!({ "messages": messages })),
        ),
        Err(e) => internal_err(e.to_string()),
    }
}

/// `POST /admin/messages/send` request body (V64).
#[derive(Debug, Deserialize)]
struct SendMessageRequest {
    from_workspace: String,
    from_project: String,
    to_workspace: String,
    to_project: String,
    #[serde(default)]
    subject: Option<String>,
    #[serde(default)]
    nature: ai_memory_core::MessageNature,
    #[serde(default)]
    evidence: Option<String>,
    body: String,
}

/// Map a message-store failure to a response. `InvalidState` is the
/// full-inbox rejection (`ops::MAX_PENDING_INBOX_MESSAGES`) — a caller error,
/// not a server fault, so it surfaces as 409 rather than 500 (mirrors
/// [`map_user_store_err`]).
fn map_message_store_err(e: StoreError) -> (StatusCode, Json<serde_json::Value>) {
    match e {
        StoreError::InvalidState(msg) => (
            StatusCode::CONFLICT,
            Json(serde_json::json!({ "error": msg })),
        ),
        other => internal_err(other.to_string()),
    }
}

/// `POST /admin/messages/send` — drop a message into another project's
/// inbox (V64). Both scopes are resolved with the no-create lookup: sending
/// to a typo'd project must fail closed rather than silently creating it.
///
/// Security: `body` and `subject` are secret-scrubbed with the same
/// [`ai_memory_core::Sanitizer`] the hook ingress uses before they are
/// capped and stored — this endpoint is not a path around redaction.
async fn handle_send_message(
    State(state): State<Arc<AdminState>>,
    actor_ext: Option<axum::Extension<ai_memory_core::ActorContext>>,
    level_ext: Option<axum::Extension<ai_memory_core::AuthLevel>>,
    headers: HeaderMap,
    Json(req): Json<SendMessageRequest>,
) -> impl IntoResponse {
    let (from_ws, from_proj) =
        match lookup_ws_proj_no_create(&state, &req.from_workspace, &req.from_project).await {
            Ok(ids) => ids,
            Err(e) => return e,
        };
    let (to_ws, to_proj) =
        match lookup_ws_proj_no_create(&state, &req.to_workspace, &req.to_project).await {
            Ok(ids) => ids,
            Err(e) => return e,
        };

    let sanitizer = ai_memory_core::Sanitizer::builtin();
    let body =
        ai_memory_core::truncate_utf8_bytes(&sanitizer.scrub(&req.body), MESSAGE_BODY_MAX_CHARS);
    let subject = req
        .subject
        .as_deref()
        .map(|s| {
            ai_memory_core::truncate_utf8_bytes(&sanitizer.scrub(s), MESSAGE_SUBJECT_MAX_CHARS)
        })
        .filter(|s| !s.is_empty());
    let evidence = req
        .evidence
        .as_deref()
        .map(|value| {
            ai_memory_core::truncate_utf8_bytes(&sanitizer.scrub(value), MESSAGE_EVIDENCE_MAX_CHARS)
        })
        .filter(|value| !value.trim().is_empty());
    if req.nature == ai_memory_core::MessageNature::Measured && evidence.is_none() {
        return (
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "error": "evidence_required: measured messages require non-empty evidence"
            })),
        );
    }

    let distinguishes = match state
        .reader
        .distinguishes_operators(state.trusted_proxy_identity)
        .await
    {
        Ok(d) => d,
        Err(e) => return internal_err(e.to_string()),
    };
    // Owner is the sender's storage key, same as `handoff_begin` — attribution
    // only (never a read filter), and `None` when the actor is anonymous or
    // the deployment doesn't tell its operators apart.
    let from_owner_user = ai_memory_core::owner_stamp(
        actor_ext
            .as_ref()
            .and_then(|axum::Extension(actor)| actor.identity_key())
            .as_ref(),
        distinguishes,
    );

    let message = ai_memory_core::NewAgentMessage {
        from_workspace_id: from_ws,
        from_project_id: from_proj,
        from_agent: AgentKind::Other,
        from_session_id: None,
        from_owner_user,
        to_workspace_id: to_ws,
        to_project_id: to_proj,
        to_agent: None,
        subject,
        body,
        nature: req.nature,
        evidence,
    };

    // Match MCP's crossing-point admission and post-commit observer ordering.
    // CLI sends must not silently bypass a configured message_send subscriber.
    let actor = actor_ext
        .map(|axum::Extension(actor)| actor)
        .unwrap_or_else(ai_memory_core::ActorContext::anonymous);
    let admission = match state
        .wiki
        .authorize_operation(
            to_ws,
            to_proj,
            AdmissionOp::MessageSend,
            actor,
            skip_webhooks_for_admin_request(level_ext, &headers),
        )
        .await
    {
        Ok(ctx) => ctx,
        // A refusal by policy, as on the MCP path — not a server fault.
        Err(e) => {
            return (
                StatusCode::FORBIDDEN,
                Json(serde_json::json!({
                    "error": format!("message send refused by admission: {e}")
                })),
            );
        }
    };
    match state.writer.insert_message(message).await {
        Ok(id) => {
            if let Some(ctx) = admission.as_ref() {
                state.wiki.notify_operation_observers(ctx);
            }
            (
                StatusCode::OK,
                Json(serde_json::json!({ "message_id": id.to_string() })),
            )
        }
        Err(e) => map_message_store_err(e),
    }
}

/// `POST /admin/messages/pop` request body (V64).
#[derive(Debug, Deserialize)]
struct PopMessageRequest {
    #[serde(default)]
    agent: Option<AgentKind>,
    workspace: String,
    project: String,
    #[serde(default)]
    message_id: Option<String>,
}

fn parse_optional_message_id(
    raw: Option<&str>,
) -> Result<Option<ai_memory_core::MessageId>, (StatusCode, Json<serde_json::Value>)> {
    raw.map(str::trim)
        .filter(|s| !s.is_empty())
        .map(str::parse::<ai_memory_core::MessageId>)
        .transpose()
        .map_err(|_| {
            (
                StatusCode::BAD_REQUEST,
                Json(serde_json::json!({ "error": "message_id must be a full UUID" })),
            )
        })
}

/// `POST /admin/messages/pop` — claim exactly one pending message from this
/// project's inbox (V64). With `message_id`, pops that one; otherwise the
/// oldest pending. Returns `{"message": null}` when nothing matched.
async fn handle_pop_message(
    State(state): State<Arc<AdminState>>,
    actor_ext: Option<axum::Extension<ai_memory_core::ActorContext>>,
    Json(req): Json<PopMessageRequest>,
) -> impl IntoResponse {
    let (ws, proj) = match lookup_ws_proj_no_create(&state, &req.workspace, &req.project).await {
        Ok(ids) => ids,
        Err(e) => return e,
    };
    let specific_id = match parse_optional_message_id(req.message_id.as_deref()) {
        Ok(id) => id,
        Err(e) => return e,
    };

    let distinguishes = match state
        .reader
        .distinguishes_operators(state.trusted_proxy_identity)
        .await
    {
        Ok(d) => d,
        Err(e) => return internal_err(e.to_string()),
    };
    let claiming_user = ai_memory_core::owner_stamp(
        actor_ext
            .as_ref()
            .and_then(|axum::Extension(actor)| actor.identity_key())
            .as_ref(),
        distinguishes,
    );

    let claim = ai_memory_core::MessageClaim {
        workspace_id: ws,
        project_id: proj,
        claiming_agent: req
            .agent
            .or_else(|| {
                actor_ext
                    .as_ref()
                    .and_then(|a| a.0.agent.as_deref())
                    .map(AgentKind::from_wire)
            })
            .unwrap_or(AgentKind::Other),
        claiming_session: None,
        claiming_user,
    };

    match state.writer.pop_message(claim, specific_id).await {
        Ok(Some(message)) => (
            StatusCode::OK,
            Json(serde_json::json!({
                "message": message,
                "security_notice": ai_memory_core::UNTRUSTED_MESSAGE_NOTICE,
            })),
        ),
        Ok(None) => (StatusCode::OK, Json(serde_json::json!({ "message": null }))),
        Err(e) => internal_err(e.to_string()),
    }
}

/// `POST /admin/messages/cancel` request body (V64).
#[derive(Debug, Deserialize)]
struct CancelMessagesRequest {
    workspace: String,
    project: String,
    #[serde(default)]
    message_id: Option<String>,
}

/// `POST /admin/messages/cancel` — retract still-pending outbox messages
/// this project sent (V64). With `message_id`, cancels just that one;
/// otherwise every pending message the project has sent.
async fn handle_cancel_messages(
    State(state): State<Arc<AdminState>>,
    Json(req): Json<CancelMessagesRequest>,
) -> impl IntoResponse {
    let (ws, proj) = match lookup_ws_proj_no_create(&state, &req.workspace, &req.project).await {
        Ok(ids) => ids,
        Err(e) => return e,
    };
    let specific_id = match parse_optional_message_id(req.message_id.as_deref()) {
        Ok(id) => id,
        Err(e) => return e,
    };

    match state.writer.cancel_messages(ws, proj, specific_id).await {
        Ok(cancelled) => (
            StatusCode::OK,
            Json(serde_json::json!({ "cancelled": cancelled })),
        ),
        Err(e) => internal_err(e.to_string()),
    }
}

async fn handle_pending_writes_list(
    State(state): State<Arc<AdminState>>,
    Query(query): Query<PendingWritesQuery>,
) -> impl IntoResponse {
    let (ws, proj) = match lookup_ws_proj_no_create(&state, &query.workspace, &query.project).await
    {
        Ok(ids) => ids,
        Err(e) => return e,
    };
    let status = match query
        .status
        .as_deref()
        .map(str::trim)
        .filter(|s| !s.is_empty())
    {
        Some(raw) => match raw.parse::<AutoImproveProposalStatus>() {
            Ok(status) => Some(status),
            Err(e) => {
                return (
                    StatusCode::BAD_REQUEST,
                    Json(serde_json::json!({ "error": e.to_string() })),
                );
            }
        },
        None => None,
    };
    match state
        .reader
        .list_auto_improve_proposals(ws, proj, status, query.limit.clamp(1, 200))
        .await
    {
        Ok(list) => (
            StatusCode::OK,
            Json(serde_json::to_value(list).unwrap_or_else(|_| serde_json::json!([]))),
        ),
        Err(e) => internal_err(e.to_string()),
    }
}

async fn pending_detail(
    state: &AdminState,
    raw_id: &str,
    query: &PendingWriteScopeQuery,
) -> Result<
    (
        WorkspaceId,
        ProjectId,
        ai_memory_store::OwnedAutoImproveProposalDetail,
    ),
    (StatusCode, Json<serde_json::Value>),
> {
    let id: AutoImproveProposalId = raw_id.parse().map_err(|e| {
        (
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({ "error": format!("invalid proposal id: {e}") })),
        )
    })?;
    let (ws, proj) = lookup_ws_proj_no_create(state, &query.workspace, &query.project).await?;
    let detail = state
        .reader
        .auto_improve_proposal_detail_with_owner(ws, proj, id)
        .await
        .map_err(|e| internal_err(e.to_string()))?
        .ok_or_else(|| {
            (
                StatusCode::NOT_FOUND,
                Json(serde_json::json!({ "error": "proposal not found in scope" })),
            )
        })?;
    Ok((ws, proj, detail))
}

async fn handle_pending_write_detail(
    State(state): State<Arc<AdminState>>,
    axum::extract::Path(id): axum::extract::Path<String>,
    Query(query): Query<PendingWriteScopeQuery>,
) -> impl IntoResponse {
    match pending_detail(&state, &id, &query).await {
        Ok((_, _, detail)) => (
            StatusCode::OK,
            Json(serde_json::to_value(detail).unwrap_or_else(|_| serde_json::json!({}))),
        ),
        Err(e) => e,
    }
}

async fn handle_pending_write_diff(
    State(state): State<Arc<AdminState>>,
    axum::extract::Path(id): axum::extract::Path<String>,
    Query(query): Query<PendingWriteScopeQuery>,
) -> impl IntoResponse {
    match pending_detail(&state, &id, &query).await {
        Ok((ws, proj, owned)) => {
            let detail = &owned.detail;
            let before = match state
                .reader
                .page_body_by_ids(ws, proj, detail.summary.target_path.as_str())
                .await
            {
                Ok(page) => page.map(|p| p.body).unwrap_or_default(),
                Err(e) => return internal_err(e.to_string()),
            };
            let diff = format!(
                "--- before/{path}\n+++ after/{path}\n@@\n{before}\n--- proposed ---\n{after}\n",
                path = detail.summary.target_path.as_str(),
                before = before,
                after = detail.body_markdown
            );
            (
                StatusCode::OK,
                Json(serde_json::json!({ "proposal_id": id, "diff": diff })),
            )
        }
        Err(e) => e,
    }
}

async fn handle_pending_write_approve(
    State(state): State<Arc<AdminState>>,
    actor_ext: Option<axum::Extension<ai_memory_core::ActorContext>>,
    author_ext: Option<axum::Extension<ai_memory_core::UserId>>,
    level_ext: Option<axum::Extension<ai_memory_core::AuthLevel>>,
    headers: HeaderMap,
    axum::extract::Path(id): axum::extract::Path<String>,
    Query(query): Query<PendingWriteScopeQuery>,
) -> impl IntoResponse {
    let proposal_id: AutoImproveProposalId = match id.parse() {
        Ok(id) => id,
        Err(e) => {
            return (
                StatusCode::BAD_REQUEST,
                Json(serde_json::json!({ "error": format!("invalid proposal id: {e}") })),
            );
        }
    };
    let (ws, proj) = match lookup_ws_proj_no_create(&state, &query.workspace, &query.project).await
    {
        Ok(ids) => ids,
        Err(e) => return e,
    };
    let actor = actor_ext
        .map(|axum::Extension(actor)| actor)
        .unwrap_or_else(ai_memory_core::ActorContext::anonymous);
    let author_id = author_ext.map(|axum::Extension(author_id)| author_id);
    let skip_webhooks = skip_webhooks_for_admin_request(level_ext, &headers);
    let admission_ctx = Some(AdmissionContext {
        op: AdmissionOp::WritePage,
        skip_webhooks,
        ..AdmissionContext::default()
    });
    // #1205: an unknown or foreign-scope id must answer 404, not 500.
    // Validate up front through the same helper the detail and diff
    // routes already use; a missing id becomes 404 here too, and an
    // unparsable id (handled inside the helper) stays 400.
    if let Err(e) = pending_detail(&state, &id, &query).await {
        return e;
    }
    match state
        .wiki
        .approve_auto_improve_proposal(ws, proj, proposal_id, actor, author_id, admission_ctx)
        .await
    {
        Ok(ApproveAutoImproveProposalResult::Approved { page_id }) => (
            StatusCode::OK,
            Json(serde_json::json!({ "status": "approved", "page_id": page_id.to_string() })),
        ),
        Ok(ApproveAutoImproveProposalResult::Conflict) => (
            StatusCode::CONFLICT,
            Json(serde_json::json!({ "status": "conflict" })),
        ),
        Err(e) => internal_err(e.to_string()),
    }
}

async fn handle_pending_write_reject(
    State(state): State<Arc<AdminState>>,
    actor_ext: Option<axum::Extension<ai_memory_core::ActorContext>>,
    author_ext: Option<axum::Extension<ai_memory_core::UserId>>,
    axum::extract::Path(id): axum::extract::Path<String>,
    Query(query): Query<PendingWriteScopeQuery>,
    Json(body): Json<PendingRejectRequest>,
) -> impl IntoResponse {
    let proposal_id: AutoImproveProposalId = match id.parse() {
        Ok(id) => id,
        Err(e) => {
            return (
                StatusCode::BAD_REQUEST,
                Json(serde_json::json!({ "error": format!("invalid proposal id: {e}") })),
            );
        }
    };
    // #1205: an unknown or foreign-scope id must answer 404, not 500.
    // Validate up front through the same helper the detail and diff
    // routes already use; a missing id becomes 404 here too, and an
    // unparsable id (handled inside the helper) stays 400.
    if let Err(e) = pending_detail(&state, &id, &query).await {
        return e;
    }
    let (ws, proj) = match lookup_ws_proj_no_create(&state, &query.workspace, &query.project).await
    {
        Ok(ids) => ids,
        Err(e) => return e,
    };
    let actor = actor_ext
        .map(|axum::Extension(actor)| actor)
        .unwrap_or_else(ai_memory_core::ActorContext::anonymous);
    match state
        .writer
        .reject_auto_improve_proposal(RejectAutoImproveProposal {
            workspace_id: ws,
            project_id: proj,
            proposal_id,
            reason: body.reason,
            actor,
            author_id: author_ext.map(|axum::Extension(author_id)| author_id),
        })
        .await
    {
        Ok(()) => (
            StatusCode::OK,
            Json(serde_json::json!({ "status": "rejected" })),
        ),
        Err(e) => internal_err(e.to_string()),
    }
}

// ---------------------------------------------------------------------
// reorg
// ---------------------------------------------------------------------

/// JSON request body for `POST /admin/reorg`.
#[derive(Deserialize)]
struct ReorgRequest {
    /// Show what would change without writing.
    #[serde(default)]
    dry_run: bool,
}

/// One entry in the reorg plan (serialised in the response).
#[derive(Debug, Serialize)]
pub struct ReorgPlanEntry {
    /// Session UUID string.
    pub session_id: String,
    /// Working directory the session was started in.
    pub cwd: String,
    /// Basename-derived project name the session will move to.
    pub new_project: String,
}

/// Summary counts returned alongside the plan.
#[derive(Debug, Serialize)]
pub struct ReorgSummaryJson {
    /// Sessions whose `project_id` was changed.
    pub sessions_moved: usize,
    /// Observations updated to match their session's new project.
    pub observations_updated: usize,
    /// `is_latest=1` pages marked `is_latest=0` (mash-up graveyard).
    pub pages_graveyarded: usize,
    /// Number of distinct per-cwd projects referenced in the plan.
    pub distinct_new_projects: usize,
}

/// Full response for `POST /admin/reorg`.
#[derive(Debug, Serialize)]
pub struct ReorgReport {
    /// `true` when `dry_run` was requested.
    pub dry_run: bool,
    /// All sessions that need (or needed) moving, with their target project.
    pub plan: Vec<ReorgPlanEntry>,
    /// Counts after execution (zeros when `dry_run=true`).
    pub summary: ReorgSummaryJson,
}

/// Read every session that has a non-empty `cwd` field, returning
/// `(session_id, project_id, cwd)` triples ordered by `started_at`.
async fn list_sessions_with_cwd(
    reader: &ai_memory_store::ReaderPool,
    workspace_id: WorkspaceId,
) -> Result<Vec<(SessionId, ProjectId, String)>, StoreError> {
    reader
        .with_conn(move |conn| {
            let mut stmt = conn.prepare(
                "SELECT id, project_id, cwd \
                     FROM sessions \
                     WHERE workspace_id = ?1 AND cwd IS NOT NULL AND cwd != '' \
                     ORDER BY started_at",
            )?;
            let rows = stmt.query_map([workspace_id.as_bytes().as_slice()], |row| {
                let id_bytes: Vec<u8> = row.get(0)?;
                let proj_bytes: Vec<u8> = row.get(1)?;
                let cwd: String = row.get(2)?;
                Ok((id_bytes, proj_bytes, cwd))
            })?;
            let mut out = Vec::new();
            for r in rows {
                let (id_bytes, proj_bytes, cwd) = r?;
                let sid = SessionId::from_slice(&id_bytes).map_err(StoreError::Memory)?;
                let pid = ProjectId::from_slice(&proj_bytes).map_err(StoreError::Memory)?;
                out.push((sid, pid, cwd));
            }
            Ok(out)
        })
        .await
}

/// Build the reorg plan: for each session with a new project basename,
/// resolve-or-create the target project, return the plan entries plus
/// the set of session updates and the distinct-project count.
async fn build_reorg_plan(
    state: &AdminState,
    ws: WorkspaceId,
    sessions: Vec<(SessionId, ProjectId, String)>,
) -> Result<(Vec<ReorgPlanEntry>, Vec<(SessionId, ProjectId)>, usize), StoreError> {
    // Resolve target project per distinct cwd (basename-derived).
    let mut cwd_to_proj: std::collections::HashMap<String, (WorkspaceId, ProjectId, String)> =
        std::collections::HashMap::new();
    for (_, _, cwd) in &sessions {
        if cwd_to_proj.contains_key(cwd.as_str()) {
            continue;
        }
        let project_name = std::path::Path::new(cwd.as_str())
            .file_name()
            .and_then(|s| s.to_str())
            .filter(|s| !s.is_empty())
            .map(str::to_string)
            .unwrap_or_else(|| "unknown".to_string());
        // Capture never attributes to a reserved scope; a reorg must not
        // either, or a directory named like one would create or fill it.
        if ai_memory_core::profile::is_reserved_scope_project(&project_name) {
            continue;
        }
        let proj = state
            .writer
            .get_or_create_project(ws, project_name.clone(), repo_path_from_reorg_cwd(cwd))
            .await?;
        cwd_to_proj.insert(cwd.clone(), (ws, proj, project_name));
    }

    // Build plan — sessions whose project_id already matches are skipped.
    let mut plan_entries: Vec<ReorgPlanEntry> = Vec::new();
    let mut writer_plan: Vec<(SessionId, ProjectId)> = Vec::new();
    for (session_id, old_project_id, cwd) in &sessions {
        let Some((_, new_project_id, project_name)) = cwd_to_proj.get(cwd.as_str()) else {
            continue;
        };
        if *new_project_id == *old_project_id {
            continue;
        }
        plan_entries.push(ReorgPlanEntry {
            session_id: session_id.to_string(),
            cwd: cwd.clone(),
            new_project: project_name.clone(),
        });
        writer_plan.push((*session_id, *new_project_id));
    }

    let distinct_new_projects: std::collections::HashSet<ProjectId> =
        writer_plan.iter().map(|(_, pid)| *pid).collect();

    Ok((plan_entries, writer_plan, distinct_new_projects.len()))
}

fn repo_path_from_reorg_cwd(cwd: &str) -> Option<String> {
    let path = std::path::Path::new(cwd);
    let repo_root = ai_memory_consolidate::discover_repo_root(path).ok()?;
    cwd_is_repo_root(path, &repo_root).then(|| repo_root.to_string_lossy().into_owned())
}

fn cwd_is_repo_root(cwd: &std::path::Path, repo_root: &std::path::Path) -> bool {
    if let (Ok(a), Ok(b)) = (std::fs::canonicalize(cwd), std::fs::canonicalize(repo_root)) {
        return a == b;
    }
    let strip = |p: &std::path::Path| p.to_string_lossy().trim_end_matches('/').to_string();
    strip(cwd) == strip(repo_root)
}

async fn handle_reorg(
    State(state): State<Arc<AdminState>>,
    Json(req): Json<ReorgRequest>,
) -> impl IntoResponse {
    let ws = match state
        .writer
        .get_or_create_workspace(DEFAULT_WORKSPACE_NAME)
        .await
    {
        Ok(id) => id,
        Err(e) => {
            return (
                StatusCode::INTERNAL_SERVER_ERROR,
                Json(serde_json::json!({ "error": format!("workspace: {e}") })),
            );
        }
    };

    let sessions = match list_sessions_with_cwd(&state.reader, ws).await {
        Ok(v) => v,
        Err(e) => {
            return (
                StatusCode::INTERNAL_SERVER_ERROR,
                Json(serde_json::json!({ "error": e.to_string() })),
            );
        }
    };

    if sessions.is_empty() {
        let report = ReorgReport {
            dry_run: req.dry_run,
            plan: Vec::new(),
            summary: ReorgSummaryJson {
                sessions_moved: 0,
                observations_updated: 0,
                pages_graveyarded: 0,
                distinct_new_projects: 0,
            },
        };
        return (
            StatusCode::OK,
            Json(serde_json::to_value(&report).unwrap_or_else(|_| serde_json::json!({}))),
        );
    }

    let (plan_entries, writer_plan, distinct_count) =
        match build_reorg_plan(&state, ws, sessions).await {
            Ok(t) => t,
            Err(e) => {
                return (
                    StatusCode::INTERNAL_SERVER_ERROR,
                    Json(serde_json::json!({ "error": format!("project: {e}") })),
                );
            }
        };

    if req.dry_run || writer_plan.is_empty() {
        let report = ReorgReport {
            dry_run: req.dry_run,
            plan: plan_entries,
            summary: ReorgSummaryJson {
                sessions_moved: 0,
                observations_updated: 0,
                pages_graveyarded: 0,
                distinct_new_projects: distinct_count,
            },
        };
        return (
            StatusCode::OK,
            Json(serde_json::to_value(&report).unwrap_or_else(|_| serde_json::json!({}))),
        );
    }

    let summary = match state.writer.reorg_sessions(ws, writer_plan).await {
        Ok(s) => s,
        Err(e) => {
            return (
                StatusCode::INTERNAL_SERVER_ERROR,
                Json(serde_json::json!({ "error": e.to_string() })),
            );
        }
    };

    let report = ReorgReport {
        dry_run: false,
        plan: plan_entries,
        summary: ReorgSummaryJson {
            sessions_moved: summary.sessions_moved,
            observations_updated: summary.observations_updated,
            pages_graveyarded: summary.pages_graveyarded,
            distinct_new_projects: distinct_count,
        },
    };
    (
        StatusCode::OK,
        Json(serde_json::to_value(&report).unwrap_or_else(|_| serde_json::json!({}))),
    )
}

// ---------------------------------------------------------------------
// lint
// ---------------------------------------------------------------------

/// JSON request body for `POST /admin/lint`.
#[derive(Deserialize)]
struct LintRequest {
    /// Workspace name (must already exist).
    #[serde(default = "default_workspace")]
    workspace: String,
    /// Project name (must already exist).
    #[serde(default = "default_project")]
    project: String,
    /// Don't write the lint report page.
    #[serde(default)]
    dry_run: bool,
    /// Skip the LLM contradiction pass (rule-based findings only).
    /// When absent, defaults to `false` (LLM pass runs if a provider
    /// is configured).
    #[serde(default)]
    no_llm: bool,
}

fn default_workspace() -> String {
    DEFAULT_WORKSPACE_NAME.to_string()
}

fn default_project() -> String {
    DEFAULT_PROJECT_NAME.to_string()
}

async fn handle_lint(
    State(state): State<Arc<AdminState>>,
    Json(req): Json<LintRequest>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    let (ws, proj) = lookup_ws_proj_no_create(&state, &req.workspace, &req.project).await?;

    run_lint(
        &state.reader,
        &state.wiki,
        state.llm.as_ref(),
        ws,
        proj,
        ai_memory_consolidate::LintOptions {
            dry_run: req.dry_run,
            use_llm: !req.no_llm,
            decay_lambda: state.decay_params.lambda,
            // Zero-LLM contradiction detection (A5) off the configured
            // embedder's triple; `None` ⇒ clean no-op.
            embedding: state
                .embedder
                .as_ref()
                .map(|e| ai_memory_consolidate::EmbeddingCoord {
                    provider: e.provider().to_string(),
                    model: e.model_identity(),
                    dim: e.dim(),
                }),
            contradiction_band_min: state.contradiction_band_min,
            contradiction_band_max: state.contradiction_band_max,
        },
    )
    .await
    .map(|report| {
        (
            StatusCode::OK,
            Json(serde_json::to_value(&report).unwrap_or_else(|_| serde_json::json!({}))),
        )
    })
    .map_err(|e| internal_err(e.to_string()))
}

// ---------------------------------------------------------------------
// forget-sweep
// ---------------------------------------------------------------------

/// JSON request body for `POST /admin/forget-sweep`.
#[derive(Deserialize)]
struct ForgetSweepRequest {
    /// Workspace name (must already exist).
    #[serde(default = "default_workspace")]
    workspace: String,
    /// Project name (must already exist).
    #[serde(default = "default_project")]
    project: String,
    /// Report what would be evicted without actually mutating.
    #[serde(default)]
    dry_run: bool,
}

async fn handle_forget_sweep(
    State(state): State<Arc<AdminState>>,
    axum::Extension(tuning): axum::Extension<SweepTuning>,
    Json(req): Json<ForgetSweepRequest>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    let (ws, proj) = lookup_ws_proj_no_create(&state, &req.workspace, &req.project).await?;

    run_sweep_with_ledgers(
        &state.reader,
        &state.writer,
        Some(&state.wiki),
        ws,
        proj,
        &state.decay_params,
        tuning.breadth_weight,
        tuning.retention,
        tuning.compact_cold_episodic,
        ColdClusterDedup::default(),
        tuning.ledger_retention,
        req.dry_run,
    )
    .await
    .map(|report| {
        (
            StatusCode::OK,
            Json(serde_json::to_value(&report).unwrap_or_else(|_| serde_json::json!({}))),
        )
    })
    .map_err(|e| internal_err(e.to_string()))
}

// ---------------------------------------------------------------------
// embed
// ---------------------------------------------------------------------

/// JSON request body for `POST /admin/embed`.
#[derive(Deserialize)]
struct EmbedRequest {
    /// Workspace name (must already exist).
    #[serde(default = "default_workspace")]
    workspace: String,
    /// Project name (must already exist). Ignored when
    /// [`Self::all_projects`] is true.
    #[serde(default = "default_project")]
    project: String,
    /// When true, regenerates embeddings even for pages that already
    /// have one matching the current (provider, model, dim).
    #[serde(default)]
    reembed: bool,
    /// When true, count pages that would be embedded/skipped without
    /// calling the embedder or writing anything.
    #[serde(default)]
    dry_run: bool,
    /// When true, embed every project in `workspace` instead of a
    /// single `project`. The CLI sets this for `--force` /
    /// `--reembed` without an explicit `--project` so model migrations
    /// reach stale rows in every namespace.
    #[serde(default)]
    all_projects: bool,
}

/// Summary response from `POST /admin/embed`.
#[derive(Debug, Serialize)]
pub struct EmbedReport {
    /// Pages that were actually embedded (zero in dry-run).
    pub embedded: usize,
    /// Pages skipped because a matching embedding already existed.
    pub skipped: usize,
    /// Pages that failed to embed (read error or provider error).
    pub failed: usize,
    /// Pages that would be embedded in a live run (only meaningful
    /// when `dry_run` was requested).
    pub would_embed: usize,
    /// Provider name.
    pub provider: String,
    /// Model identifier.
    pub model: String,
    /// Embedding dimensionality.
    pub dim: u32,
}

async fn embed_project_pages(
    state: &AdminState,
    embedder: &Arc<dyn Embedder>,
    ws: WorkspaceId,
    proj: ProjectId,
    reembed: bool,
    dry_run: bool,
) -> Result<EmbedBackfillCounts, (StatusCode, Json<serde_json::Value>)> {
    run_embedding_backfill(
        &state.reader,
        &state.writer,
        &state.wiki,
        embedder,
        ws,
        proj,
        EmbedBackfillOptions { reembed, dry_run },
    )
    .await
    .map_err(|e| internal_err(e.to_string()))
}

/// The `(provider, model, dim)` triple rows are stored under for one
/// embedder: `model_identity()` (which folds in a configured document
/// prefix), never the bare wire model name. `handle_embed`'s stale-row
/// purge and `handle_status`'s missing-vector count must both match rows
/// the way they are written, so they share this instead of each spelling
/// the triple (a vector counts as covering a page only when this very
/// identity would store one for it).
fn stored_embedding_identity(embedder: &dyn Embedder) -> (String, String, u32) {
    (
        embedder.provider().to_string(),
        embedder.model_identity(),
        embedder.dim(),
    )
}

async fn handle_embed(
    State(state): State<Arc<AdminState>>,
    Json(req): Json<EmbedRequest>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    let embedder = match state.embedder.clone() {
        Some(e) => e,
        None => {
            return Err((
                StatusCode::SERVICE_UNAVAILABLE,
                Json(serde_json::json!({
                    "error": "embedder not configured on server"
                })),
            ));
        }
    };

    let (provider, model, dim) = stored_embedding_identity(&*embedder);

    let mut totals = EmbedBackfillCounts::default();

    if req.all_projects {
        if let Some(ws) = state
            .reader
            .find_workspace(req.workspace.clone())
            .await
            .map_err(|e| internal_err(e.to_string()))?
        {
            if req.reembed && !req.dry_run {
                let purged = state
                    .writer
                    .delete_stale_page_embeddings(ws, None, provider.clone(), model.clone(), dim)
                    .await
                    .map_err(|e| internal_err(e.to_string()))?;
                info!(purged, provider = %provider, model = %model, "purged stale page_embeddings before workspace re-embed");
            }

            let summaries = state
                .reader
                .list_projects_with_stats(OPERATOR)
                .await
                .map_err(|e| internal_err(e.to_string()))?;
            for summary in summaries
                .into_iter()
                .filter(|p| p.workspace_name == req.workspace)
            {
                let Some(proj) = state
                    .reader
                    .find_project(ws, summary.project_name.clone())
                    .await
                    .map_err(|e| internal_err(e.to_string()))?
                else {
                    continue;
                };
                let partial =
                    embed_project_pages(&state, &embedder, ws, proj, req.reembed, req.dry_run)
                        .await?;
                totals.absorb(partial);
            }
        }
    } else {
        let (ws, proj) = lookup_ws_proj_no_create(&state, &req.workspace, &req.project).await?;
        if req.reembed && !req.dry_run {
            let purged = state
                .writer
                .delete_stale_page_embeddings(ws, Some(proj), provider.clone(), model.clone(), dim)
                .await
                .map_err(|e| internal_err(e.to_string()))?;
            info!(purged, provider = %provider, model = %model, "purged stale page_embeddings before project re-embed");
        }
        totals = embed_project_pages(&state, &embedder, ws, proj, req.reembed, req.dry_run).await?;
    }

    let report = EmbedReport {
        embedded: totals.embedded,
        skipped: totals.skipped,
        failed: totals.failed,
        would_embed: totals.would_embed,
        provider,
        model,
        dim,
    };
    Ok((
        StatusCode::OK,
        Json(serde_json::to_value(&report).unwrap_or_else(|_| serde_json::json!({}))),
    ))
}

// ---------------------------------------------------------------------
// commit
// ---------------------------------------------------------------------

/// JSON request body for `POST /admin/commit`.
#[derive(Deserialize)]
struct CommitRequest {
    /// Commit message.
    message: String,
}

#[derive(Debug, Serialize)]
struct CheckpointResponse {
    /// Full git commit OID.
    oid: String,
    /// First 12 hex characters, useful for CLI display.
    short_oid: String,
    /// Commit author timestamp in seconds since Unix epoch.
    time: i64,
    /// First line of the commit message.
    summary: String,
}

#[derive(Debug, Deserialize)]
struct CheckpointListQuery {
    /// Maximum number of checkpoints to return.
    #[serde(default = "default_checkpoint_limit")]
    limit: usize,
}

fn default_checkpoint_limit() -> usize {
    20
}

fn short_oid(oid: &str) -> String {
    oid.chars().take(12).collect()
}

fn checkpoint_or_500(
    wiki: &Wiki,
    message: impl AsRef<str>,
) -> Result<Option<String>, (StatusCode, Json<serde_json::Value>)> {
    wiki.commit_all(message.as_ref())
        .map(|oid| oid.map(|oid| oid.to_string()))
        .map_err(|e| internal_err(e.to_string()))
}

fn checkpoint_or_warn(wiki: &Wiki, message: impl AsRef<str>) -> Option<String> {
    match wiki.commit_all(message.as_ref()) {
        Ok(Some(oid)) => Some(oid.to_string()),
        Ok(None) => None,
        Err(e) => {
            warn!(error = %e, "wiki checkpoint failed after mutation");
            None
        }
    }
}

async fn handle_commit(
    State(state): State<Arc<AdminState>>,
    Json(req): Json<CommitRequest>,
) -> impl IntoResponse {
    match state.wiki.commit_all(&req.message) {
        Ok(Some(oid)) => (
            StatusCode::OK,
            Json(serde_json::json!({
                "committed": true,
                "oid": oid.to_string(),
            })),
        ),
        Ok(None) => (
            StatusCode::OK,
            Json(serde_json::json!({
                "committed": false,
                "reason": "nothing to commit",
            })),
        ),
        Err(e) => (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(serde_json::json!({ "error": e.to_string() })),
        ),
    }
}

async fn handle_checkpoints(
    State(state): State<Arc<AdminState>>,
    Query(query): Query<CheckpointListQuery>,
) -> impl IntoResponse {
    let limit = query.limit.clamp(1, 100);
    match state.wiki.recent_checkpoints(limit) {
        Ok(checkpoints) => {
            let checkpoints: Vec<CheckpointResponse> = checkpoints
                .into_iter()
                .map(|cp| CheckpointResponse {
                    short_oid: short_oid(&cp.oid),
                    oid: cp.oid,
                    time: cp.time,
                    summary: cp.summary,
                })
                .collect();
            (
                StatusCode::OK,
                Json(serde_json::to_value(checkpoints).unwrap_or_else(|_| serde_json::json!([]))),
            )
        }
        Err(e) => internal_err(e.to_string()),
    }
}

// ---------------------------------------------------------------------
// restore-page
// ---------------------------------------------------------------------

#[derive(Deserialize)]
struct RestorePageRequest {
    /// Workspace name. Must exist.
    workspace: String,
    /// Project name. Must exist within `workspace`.
    project: String,
    /// Relative wiki path to restore.
    path: String,
    /// Git revision/commit to restore from.
    #[serde(default)]
    rev: Option<String>,
    /// Retained SQLite page-version id to restore. Mutually exclusive with
    /// `rev`; used for histories moved by `merge-project`.
    #[serde(default)]
    page_id: Option<String>,
}

#[derive(Serialize)]
struct RestorePageResponse {
    /// UUID of the restored page version.
    page_id: String,
    /// Canonical wiki path restored.
    path: String,
    /// Revision requested by the caller.
    restored_from: String,
    /// Pre-restore checkpoint, if the current tree had changes to save.
    #[serde(skip_serializing_if = "Option::is_none")]
    pre_checkpoint: Option<String>,
    /// Post-restore checkpoint, if the restore changed the tree.
    #[serde(skip_serializing_if = "Option::is_none")]
    checkpoint: Option<String>,
}

async fn handle_restore_page(
    State(state): State<Arc<AdminState>>,
    Json(req): Json<RestorePageRequest>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    let path = PagePath::new(req.path.clone()).map_err(|e| {
        (
            StatusCode::UNPROCESSABLE_ENTITY,
            Json(serde_json::json!({ "error": format!("invalid path: {e}") })),
        )
    })?;
    let (ws, proj) = lookup_ws_proj_no_create(&state, &req.workspace, &req.project).await?;
    let (restore_source, version_id) = match (&req.rev, &req.page_id) {
        (Some(rev), None) if !rev.trim().is_empty() => (rev.clone(), None),
        (None, Some(page_id)) if !page_id.trim().is_empty() => {
            let version = page_id.parse::<PageId>().map_err(|_| {
                (
                    StatusCode::BAD_REQUEST,
                    Json(serde_json::json!({"error": "invalid page_id"})),
                )
            })?;
            (format!("page version {page_id}"), Some(version))
        }
        _ => {
            return Err((
                StatusCode::BAD_REQUEST,
                Json(serde_json::json!({
                    "error": "exactly one of rev or page_id is required"
                })),
            ));
        }
    };

    let pre_checkpoint = checkpoint_or_500(
        &state.wiki,
        format!(
            "pre-restore-page {}/{}: {}",
            req.workspace,
            req.project,
            path.as_str()
        ),
    )?;

    let page_id = if let Some(rev) = &req.rev {
        state
            .wiki
            .restore_page_from_checkpoint(ws, proj, path.clone(), rev)
            .await
            .map_err(|e| internal_err(e.to_string()))?
    } else {
        let version = version_id
            .ok_or_else(|| internal_err("validated page-version restore lost its version id"))?;
        state
            .wiki
            .restore_page_from_version(ws, proj, path.clone(), version)
            .await
            .map_err(|error| match error {
                WikiError::Store(StoreError::NotFound(_)) => (
                    StatusCode::NOT_FOUND,
                    Json(serde_json::json!({"error": error.to_string()})),
                ),
                _ => internal_err(error.to_string()),
            })?
    };
    let checkpoint = checkpoint_or_warn(
        &state.wiki,
        format!(
            "restore-page {}/{}: {} from {}",
            req.workspace,
            req.project,
            path.as_str(),
            restore_source
        ),
    );

    Ok((
        StatusCode::OK,
        Json(
            serde_json::to_value(RestorePageResponse {
                page_id: page_id.to_string(),
                path: path.to_string(),
                restored_from: restore_source,
                pre_checkpoint,
                checkpoint,
            })
            .unwrap_or_else(|_| serde_json::json!({})),
        ),
    ))
}

// ---------------------------------------------------------------------
// purge-session
// ---------------------------------------------------------------------

/// JSON request body for `POST /admin/purge-session`.
#[derive(Deserialize)]
struct PurgeSessionRequest {
    /// Workspace name. Must already exist; 404 otherwise.
    workspace: String,
    /// Project name. Must already exist; 404 otherwise.
    project: String,
    /// Full `sessions.id` UUID. A session that does not belong to the named
    /// workspace/project is a 404 — the id alone is never authority over
    /// another scope.
    session_id: String,
    /// Mandatory confirmation flag. Without `confirm: true` the server
    /// returns 400 — purging is destructive and irreversible.
    #[serde(default)]
    confirm: bool,
    /// Reclaim freed bytes: rebuild the FTS indexes and `VACUUM` after the
    /// delete commits. Off by default; see `ai_memory_store::Compaction` for
    /// the cost and for what it does not guarantee.
    #[serde(default)]
    compact: bool,
    /// Preview only: report the counts a purge of this session would produce
    /// without deleting anything. Wins over `confirm` — `{"confirm": true,
    /// "dry_run": true}` still only previews, exactly like `purge-project`
    /// treats its own `dry_run` field (which itself mirrors
    /// `reclaim-ledger-versions`) — so a preview request can never
    /// accidentally become destructive. `#[serde(default)]` keeps an older
    /// CLI, built before this field existed, parsing the same request it
    /// always sent.
    #[serde(default)]
    dry_run: bool,
}

/// Wire-format summary returned by `POST /admin/purge-session`.
#[derive(Debug, Serialize)]
pub struct PurgeSessionReport {
    /// Session id that was purged.
    pub session_id: String,
    /// Human workspace name.
    pub workspace: String,
    /// Human project name.
    pub project: String,
    /// Number of observations deleted.
    pub observations_deleted: u64,
    /// Number of authored handoffs deleted.
    pub handoffs_deleted: u64,
    /// Number of page rows deleted, counting superseded versions.
    pub pages_deleted: u64,
    /// Number of auto-improvement runs deleted.
    pub auto_improve_runs_deleted: u64,
    /// Distinct wiki page paths whose database rows were deleted.
    pub removed_paths: Vec<PagePath>,
    /// `observations` rows in a **different** project, deleted collaterally
    /// because their `session_id` is this session (`observations.session_id`
    /// is `ON DELETE CASCADE`, without regard to the observation's own
    /// `project_id`). Always present, zero when there is none, so a caller
    /// can tell "no collateral damage" apart from "field absent on an older
    /// server".
    pub collateral_observations_deleted: u64,
    /// `handoffs` rows in a different project whose `from_session_id` or
    /// `accepted_by_session` is set to `NULL` (not deleted — those columns
    /// are `ON DELETE SET NULL`) because they referenced this session.
    pub collateral_handoffs_denulled: u64,
    /// Distinct wiki page paths removed from disk after the database purge.
    pub files_deleted: Vec<PagePath>,
    /// Distinct wiki page paths that could not be removed from disk.
    pub files_failed: Vec<PagePath>,
    /// Whether the freed bytes were reclaimed (`VACUUM` ran).
    pub compacted: bool,
    /// Pre-purge checkpoint, if the tree had uncommitted changes.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub pre_checkpoint: Option<String>,
    /// Post-purge checkpoint, if the purge changed the tree.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub checkpoint: Option<String>,
    /// `true` for a preview: `dry_run: true` in the request always wins over
    /// `confirm`, so this is only ever `false` on a run that actually
    /// deleted rows. `removed_paths` on a preview are paths a confirmed
    /// purge *would* remove; `files_deleted`/`files_failed` are always empty
    /// and `pre_checkpoint`/`checkpoint` always absent, since no wiki file
    /// was touched, no admission webhook ran, and no audit row was written.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub dry_run: bool,
}

/// `POST /admin/purge-session` — delete one session and everything derived
/// from it, inside a single workspace/project scope.
async fn handle_purge_session(
    State(state): State<Arc<AdminState>>,
    actor_ext: Option<axum::Extension<ai_memory_core::ActorContext>>,
    author_ext: Option<axum::Extension<ai_memory_core::UserId>>,
    Json(req): Json<PurgeSessionRequest>,
) -> impl IntoResponse {
    let author_id = author_ext.map(|axum::Extension(u)| u);
    // `dry_run` always wins, exactly like `purge-project`: `{"confirm":
    // true, "dry_run": true}` must never run the destructive path just
    // because `confirm` also happened to be set.
    if req.dry_run {
        return purge_session_preview(&state, &req, author_id).await;
    }
    if !req.confirm {
        return (
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "error": "destructive operation requires confirm=true"
            })),
        );
    }

    let session_id = match req.session_id.trim().parse::<SessionId>() {
        Ok(id) => id,
        Err(_) => {
            return (
                StatusCode::BAD_REQUEST,
                Json(serde_json::json!({ "error": "session_id must be a full UUID" })),
            );
        }
    };

    let (ws_id, proj_id) =
        match lookup_ws_proj_no_create(&state, &req.workspace, &req.project).await {
            Ok(ids) => ids,
            Err(e) => return e,
        };

    // Admission runs before anything is deleted so a reject-policy webhook can
    // refuse while every row is still intact — same order as purge-project.
    let actor = actor_ext
        .map(|axum::Extension(a)| a)
        .unwrap_or_else(ai_memory_core::ActorContext::anonymous);
    let ctx = AdmissionContext {
        workspace: req.workspace.clone(),
        project: req.project.clone(),
        op: AdmissionOp::PurgeSession,
        actor,
        ..Default::default()
    };
    let mut dispatch_ctx = match state
        .wiki
        .admit_purge_session(ws_id, proj_id, Some(ctx))
        .await
    {
        Ok(ctx) => ctx,
        Err(e) => return internal_err(e.to_string()),
    };

    let label = format!("{}/{}: {}", req.workspace, req.project, session_id);
    let pre_checkpoint = match checkpoint_or_500(&state.wiki, format!("pre-purge-session {label}"))
    {
        Ok(oid) => oid,
        Err(e) => return e,
    };

    let compaction = if req.compact {
        ai_memory_store::Compaction::Reclaim
    } else {
        ai_memory_store::Compaction::Skip
    };

    let outcome = match state
        .wiki
        .purge_session(ws_id, proj_id, session_id, author_id, compaction)
        .await
    {
        Ok(s) => s,
        // Absent from this scope (or already purged) is a 404, not a fault.
        Err(WikiError::Store(e @ StoreError::NotFound(_))) => {
            return (
                StatusCode::NOT_FOUND,
                Json(serde_json::json!({ "error": e.to_string() })),
            );
        }
        Err(e) => return internal_err(e.to_string()),
    };

    let ai_memory_wiki::PurgeSessionOutcome {
        summary,
        files_deleted,
        files_failed,
    } = outcome;
    if !files_failed.is_empty()
        && let Some(ref mut ctx) = dispatch_ctx
    {
        ctx.partial_failure = true;
    }
    state.wiki.dispatch_purge(dispatch_ctx.as_ref());

    let checkpoint = checkpoint_or_warn(&state.wiki, format!("purge-session {label}"));

    let report = PurgeSessionReport {
        session_id: session_id.to_string(),
        workspace: req.workspace,
        project: req.project,
        observations_deleted: summary.observations_deleted,
        handoffs_deleted: summary.handoffs_deleted,
        pages_deleted: summary.pages_deleted,
        auto_improve_runs_deleted: summary.auto_improve_runs_deleted,
        removed_paths: summary.removed_paths,
        collateral_observations_deleted: summary.collateral_observations_deleted,
        collateral_handoffs_denulled: summary.collateral_handoffs_denulled,
        files_deleted,
        files_failed,
        compacted: summary.compacted,
        pre_checkpoint,
        checkpoint,
        dry_run: false,
    };

    (StatusCode::OK, Json(json_or_empty(&report)))
}

/// Preview branch of `POST /admin/purge-session`: reached whenever `dry_run`
/// is true, regardless of `confirm` (see the `dry_run`-always-wins check in
/// `handle_purge_session`). Goes straight through `state.writer.purge_session`
/// under [`ai_memory_store::PurgeMode::Preview`] — bypassing `Wiki::purge_session`
/// entirely, unlike the confirmed path above — because that wrapper's
/// file-removal loop walks `summary.removed_paths` and deletes each one from
/// disk; under `PurgeMode::Preview` those paths are *predictions*, not rows
/// that are actually gone, and running the wrapper would delete a live wiki
/// file the database still points to.
///
/// Deliberately skipped, mirroring `purge-project`'s preview: the blocking
/// admission call (`admit_purge_session`, nothing was decided yet), wiki file
/// removal, and both checkpoints (the git tree does not change). Because
/// admission never runs, a `200` here is not a promise the confirmed purge
/// will succeed.
///
/// Scope resolution and its `404` run exactly as the real purge's do, so an
/// unknown workspace/project/session answers identically either way.
async fn purge_session_preview(
    state: &Arc<AdminState>,
    req: &PurgeSessionRequest,
    author_id: Option<ai_memory_core::UserId>,
) -> (StatusCode, Json<serde_json::Value>) {
    let session_id = match req.session_id.trim().parse::<SessionId>() {
        Ok(id) => id,
        Err(_) => {
            return (
                StatusCode::BAD_REQUEST,
                Json(serde_json::json!({ "error": "session_id must be a full UUID" })),
            );
        }
    };

    let (ws_id, proj_id) = match lookup_ws_proj_no_create(state, &req.workspace, &req.project).await
    {
        Ok(ids) => ids,
        Err(e) => return e,
    };

    let summary = match state
        .writer
        .purge_session(
            ws_id,
            proj_id,
            session_id,
            author_id,
            // A preview never deletes anything, so there is nothing to
            // reclaim; `ops::purge_session` also forces `compacted: false`
            // for `PurgeMode::Preview` regardless of this value.
            ai_memory_store::Compaction::Skip,
            ai_memory_store::PurgeMode::Preview,
        )
        .await
    {
        Ok(s) => s,
        // Absent from this scope is a 404, not a fault — same as the
        // confirmed path.
        Err(e @ StoreError::NotFound(_)) => {
            return (
                StatusCode::NOT_FOUND,
                Json(serde_json::json!({ "error": e.to_string() })),
            );
        }
        Err(e) => return internal_err(e.to_string()),
    };

    let report = PurgeSessionReport {
        session_id: session_id.to_string(),
        workspace: req.workspace.clone(),
        project: req.project.clone(),
        observations_deleted: summary.observations_deleted,
        handoffs_deleted: summary.handoffs_deleted,
        pages_deleted: summary.pages_deleted,
        auto_improve_runs_deleted: summary.auto_improve_runs_deleted,
        removed_paths: summary.removed_paths,
        collateral_observations_deleted: summary.collateral_observations_deleted,
        collateral_handoffs_denulled: summary.collateral_handoffs_denulled,
        files_deleted: Vec::new(),
        files_failed: Vec::new(),
        compacted: false,
        pre_checkpoint: None,
        checkpoint: None,
        dry_run: true,
    };

    (StatusCode::OK, Json(json_or_empty(&report)))
}

// ---------------------------------------------------------------------
// repair-session-times
// ---------------------------------------------------------------------

/// Upper bound on how many session candidates one
/// `POST /admin/repair-session-times` request may carry. The CLI builds this
/// list from a local transcript scan, which is operator-controlled, but the
/// request body is still client-supplied input to a single writer-actor
/// transaction — bounding it keeps that transaction (and the rolled-back dry
/// run alike) from growing unboundedly on a malformed or hostile request.
/// Comfortably above what one project's transcript history should ever
/// produce; the CLI chunks larger batches into requests of this size.
const MAX_REPAIR_SESSIONS: usize = 2_000;

/// One candidate session correction in `POST /admin/repair-session-times`.
#[derive(Deserialize)]
struct RepairSessionTimesItem {
    /// Full `sessions.id` UUID (native id or its UUID v5, already resolved by
    /// the caller — same rule the hook router uses).
    session_id: String,
    /// Replacement `started_at`, Unix microseconds, read from the caller's
    /// transcript.
    started_at_us: i64,
    /// Replacement `ended_at`, or omitted/`null` to leave the column as it
    /// is. Never applied when the session is currently open; see
    /// [`ai_memory_store::RepairedSessionTimes::end_kept_open`].
    #[serde(default)]
    ended_at_us: Option<i64>,
}

/// JSON request body for `POST /admin/repair-session-times`.
#[derive(Deserialize)]
struct RepairSessionTimesRequest {
    /// Workspace name. Must already exist; 404 otherwise.
    workspace: String,
    /// Project name. Must already exist; 404 otherwise.
    project: String,
    /// Candidate corrections, one per session. A candidate whose
    /// `session_id` does not belong to this `(workspace, project)` is
    /// reported `not_found` and left untouched — the id alone is never
    /// authority over another scope, same as `purge-session`. A candidate
    /// naming a session whose row is not dated after the candidate's own end
    /// (i.e. is not actually flattened) is reported `not_flattened` and left
    /// untouched too — this endpoint repairs the backfill bug, it does not
    /// let a caller set an arbitrary session's times. Bounded by
    /// [`MAX_REPAIR_SESSIONS`].
    sessions: Vec<RepairSessionTimesItem>,
    /// Without `confirm: true` this is a real dry run: every candidate is
    /// validated and the exact would-be outcome is reported, but nothing is
    /// written.
    #[serde(default)]
    confirm: bool,
}

/// One session actually rewritten (or, for a dry run, that would be),
/// mirrored from [`ai_memory_store::RepairedSessionTimes`].
#[derive(Debug, Serialize)]
pub struct RepairedSessionTimesReport {
    /// Session that was rewritten (or, for a dry run, that would be).
    pub session_id: String,
    /// `started_at` before the repair.
    pub old_started_at_us: i64,
    /// `ended_at` before the repair.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub old_ended_at_us: Option<i64>,
    /// `started_at` after the repair.
    pub new_started_at_us: i64,
    /// `ended_at` after the repair (unchanged when `None`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub new_ended_at_us: Option<i64>,
    /// `true` when the candidate carried `ended_at_us` but the session was
    /// open, so only `started_at` was applied.
    #[serde(skip_serializing_if = "std::ops::Not::not")]
    pub end_kept_open: bool,
}

/// One candidate left untouched, with why.
#[derive(Debug, Serialize)]
pub struct SkippedSessionTimesReport {
    /// Session the candidate named.
    pub session_id: String,
    /// `"not_found"`, `"not_flattened"`, `"unchanged"`, `"invalid_time"`,
    /// `"inverted_times"`, or `"future_time"`.
    pub reason: &'static str,
}

/// Wire-format report for `POST /admin/repair-session-times`.
#[derive(Debug, Serialize)]
pub struct RepairSessionTimesReport {
    /// Human workspace name.
    pub workspace: String,
    /// Human project name.
    pub project: String,
    /// `true` when nothing was written (no `confirm`).
    pub dry_run: bool,
    /// Sessions rewritten (or, for a dry run, that would be).
    pub repaired: Vec<RepairedSessionTimesReport>,
    /// Sessions left untouched, with why — includes scope mismatches
    /// (`"not_found"`), sessions not matching the bug's signature
    /// (`"not_flattened"`), no-op candidates (`"unchanged"`), and refused
    /// times.
    pub skipped: Vec<SkippedSessionTimesReport>,
}

fn repair_skip_reason_label(reason: ai_memory_store::SessionTimesSkipReason) -> &'static str {
    match reason {
        ai_memory_store::SessionTimesSkipReason::NotFound => "not_found",
        ai_memory_store::SessionTimesSkipReason::NotFlattened => "not_flattened",
        ai_memory_store::SessionTimesSkipReason::Unchanged => "unchanged",
        ai_memory_store::SessionTimesSkipReason::InvalidTime => "invalid_time",
        ai_memory_store::SessionTimesSkipReason::InvertedTimes => "inverted_times",
        ai_memory_store::SessionTimesSkipReason::FutureTime => "future_time",
    }
}

/// `POST /admin/repair-session-times` — correct `sessions.started_at`/
/// `ended_at` for sessions already imported by an older `backfill` that
/// discarded the transcript's own timestamps.
///
/// The CLI (`ai-memory repair-backfill-timestamps`) owns transcript access —
/// it reads the operator's local harness transcripts, matches each one to a
/// session id, and posts the computed candidate times here; this endpoint
/// never touches the filesystem. Every candidate is validated against the
/// scope: a `session_id` that does not belong to `(workspace, project)` is
/// `not_found`, exactly like `purge-session`. A candidate whose named session
/// is not actually flattened (its `started_at` does not postdate the
/// candidate's own end) is `not_flattened` and left untouched — this targets
/// the backfill bug specifically, it is not a generic "set session times"
/// primitive that would happily rewrite a correctly hook-captured session.
/// Without `confirm` the write runs inside a rolled-back transaction, so the
/// report is the literal would-be outcome (same pattern as `move-session`). A
/// confirmed batch writes one `audit_log` row with the repaired sessions'
/// before/after times, which is the reversibility an operator has after the
/// fact.
async fn handle_repair_session_times(
    State(state): State<Arc<AdminState>>,
    author_ext: Option<axum::Extension<ai_memory_core::UserId>>,
    Json(req): Json<RepairSessionTimesRequest>,
) -> (StatusCode, Json<serde_json::Value>) {
    let author_id = author_ext.map(|axum::Extension(u)| u);
    if req.sessions.len() > MAX_REPAIR_SESSIONS {
        return (
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "error": format!(
                    "sessions: at most {MAX_REPAIR_SESSIONS} candidates per request, got {}",
                    req.sessions.len()
                )
            })),
        );
    }

    let (ws_id, proj_id) =
        match lookup_ws_proj_no_create(&state, &req.workspace, &req.project).await {
            Ok(ids) => ids,
            Err((status, body)) => return (status, body),
        };

    // Parsed locally (not via the writer) so a single malformed id fails the
    // whole request before anything is validated against the scope, same as
    // `purge-session`'s UUID check.
    let mut candidates = Vec::with_capacity(req.sessions.len());
    let mut malformed = Vec::new();
    for item in &req.sessions {
        match item.session_id.trim().parse::<SessionId>() {
            Ok(session_id) => candidates.push(ai_memory_store::SessionTimesCandidate {
                session_id,
                started_at_us: item.started_at_us,
                ended_at_us: item.ended_at_us,
            }),
            Err(_) => malformed.push(item.session_id.clone()),
        }
    }
    if !malformed.is_empty() {
        return (
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "error": "session_id must be a full UUID",
                "malformed": malformed,
            })),
        );
    }

    let now_us = jiff::Timestamp::now().as_microsecond();
    let outcome = match state
        .writer
        .repair_session_times(ws_id, proj_id, candidates, now_us, author_id, req.confirm)
        .await
    {
        Ok(summary) => summary,
        Err(e) => {
            return (
                StatusCode::INTERNAL_SERVER_ERROR,
                Json(serde_json::json!({ "error": e.to_string() })),
            );
        }
    };

    let report = RepairSessionTimesReport {
        workspace: req.workspace,
        project: req.project,
        dry_run: !req.confirm,
        repaired: outcome
            .repaired
            .into_iter()
            .map(|r| RepairedSessionTimesReport {
                session_id: r.session_id.to_string(),
                old_started_at_us: r.old_started_at_us,
                old_ended_at_us: r.old_ended_at_us,
                new_started_at_us: r.new_started_at_us,
                new_ended_at_us: r.new_ended_at_us,
                end_kept_open: r.end_kept_open,
            })
            .collect(),
        skipped: outcome
            .skipped
            .into_iter()
            .map(|s| SkippedSessionTimesReport {
                session_id: s.session_id.to_string(),
                reason: repair_skip_reason_label(s.reason),
            })
            .collect(),
    };

    (StatusCode::OK, Json(json_or_empty(&report)))
}

// ---------------------------------------------------------------------
// purge-project
// ---------------------------------------------------------------------

/// JSON request body for `POST /admin/purge-project`.
#[derive(Deserialize)]
struct PurgeProjectRequest {
    /// Workspace name. The workspace must already exist; we 404 if absent.
    workspace: String,
    /// Project name. The project must already exist; we 404 if absent.
    /// Mutually exclusive with `project_id`; the CLI sends whichever the
    /// operator chose and leaves the other `None`. (#1208)
    #[serde(default)]
    project: Option<String>,
    /// Project id (UUID string). Bypasses the name/legacy/canonical lookup
    /// and targets the row directly, so an operator can disambiguate a name
    /// collision. Server returns 400 on bad UUID parse, 404 on unknown id or
    /// foreign-scope id. (#1208)
    #[serde(default)]
    project_id: Option<String>,
    /// Mandatory confirmation flag. Without `confirm: true` the server
    /// returns 400 — purging is destructive and irreversible.
    #[serde(default)]
    confirm: bool,
    /// Purge even when a managed workstream under this project still holds a
    /// live run lease. Off by default: the cascade would delete that lease row
    /// out from under a running agent, which then cannot save its history.
    #[serde(default)]
    force: bool,
    /// Reclaim freed bytes: rebuild the FTS indexes and `VACUUM` after the
    /// delete commits. Off by default; see `ai_memory_store::Compaction` for
    /// the cost and for what it does not guarantee.
    #[serde(default)]
    compact: bool,
    /// Preview only: report the counts a purge of this scope would produce
    /// without deleting anything. Wins over `confirm` — `{"confirm": true,
    /// "dry_run": true}` still only previews, exactly like
    /// `reclaim-ledger-versions` treats its own `dry_run` field — so a
    /// preview request can never accidentally become destructive.
    /// `#[serde(default)]` here is what keeps an *old* CLI (built before this
    /// field existed, so it never sends `dry_run` at all) parsing the same
    /// request it always sent. The other direction — a *new* CLI talking to
    /// an *old* server that doesn't know this field yet — needs nothing on
    /// this struct at all: an unknown JSON field is simply not a
    /// `Deserialize` error on the server, so the old server ignores it and
    /// the new CLI's fallback (see `commands/purge_project.rs`) handles the
    /// resulting plain 400.
    #[serde(default)]
    dry_run: bool,
}

/// Wire-format summary returned by `POST /admin/purge-project`.
#[derive(Debug, Serialize)]
pub struct PurgeProjectReport {
    /// Human-readable `workspace/project` label.
    pub label: String,
    /// Number of `pages` rows deleted (all versions).
    pub pages_deleted: u64,
    /// Number of `sessions` rows deleted.
    pub sessions_deleted: u64,
    /// Number of `observations` rows deleted.
    pub observations_deleted: u64,
    /// Number of `handoffs` rows deleted.
    pub handoffs_deleted: u64,
    /// Number of `page_embeddings` rows deleted.
    pub embeddings_deleted: u64,
    /// `observations` rows in a **different** project, deleted collaterally
    /// because their `session_id` belongs to a session that lives in this
    /// one (`observations.session_id` is `ON DELETE CASCADE`, without regard
    /// to the observation's own `project_id`) — the mirror of the incident
    /// this preview guards against. Always present, zero when there is none,
    /// so a caller can tell "no collateral damage" apart from "field absent
    /// on an older server".
    pub collateral_observations_deleted: u64,
    /// `handoffs` rows in a different project whose `from_session_id` or
    /// `accepted_by_session` is set to `NULL` (not deleted — those columns
    /// are `ON DELETE SET NULL`) because they referenced a session that
    /// lives in this project.
    pub collateral_handoffs_denulled: u64,
    /// Number of managed `workstreams` rows deleted via cascade.
    pub workstreams_deleted: u64,
    /// Number of `managed_runs` rows deleted via cascade.
    pub managed_runs_deleted: u64,
    /// Ids of the deleted workstreams whose `raw/workstreams/<id>/` segment
    /// directories were included in the post-commit cleanup.
    pub workstream_ids: Vec<String>,
    /// Paths removed from disk (the project'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>,
    /// Whether the freed bytes were reclaimed (`VACUUM` ran). False for a
    /// plain logical delete: the rows are gone from the API and from search,
    /// but their bytes stay in free pages until the file is next rewritten.
    pub compacted: bool,
    /// Pre-purge checkpoint, if the tree had uncommitted changes.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub pre_checkpoint: Option<String>,
    /// Post-purge checkpoint, if the purge changed the tree.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub checkpoint: Option<String>,
    /// `true` for a preview: `dry_run: true` in the request always wins over
    /// `confirm`, so this is only ever `false` on a run that actually
    /// deleted rows. The counts above are read directly by the same queries
    /// a confirmed purge uses to decide what to delete — never by running
    /// the delete and rolling it back — so `files_deleted`/`files_failed`
    /// are always empty and `pre_checkpoint`/`checkpoint` always absent: no
    /// wiki file was touched, no admission webhook ran, and no audit row was
    /// written.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub dry_run: bool,
}

async fn remove_workstream_segment_storage(
    state: &AdminState,
    workstream_ids: &[String],
    operation: &'static str,
) -> (Vec<String>, Vec<String>) {
    let mut deleted = Vec::with_capacity(workstream_ids.len());
    let mut failed = Vec::new();

    for workstream_id in workstream_ids {
        let path = state
            .data_dir
            .join("raw")
            .join("workstreams")
            .join(workstream_id);
        let path_display = path.display().to_string();
        match tokio::fs::remove_dir_all(&path).await {
            Ok(()) => deleted.push(path_display),
            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
            Err(error) => {
                warn!(
                    operation,
                    path = %path_display,
                    error = %error,
                    "scope purge failed to remove workstream segment directory"
                );
                failed.push(path_display);
            }
        }
    }

    (deleted, failed)
}

async fn remove_purged_project_storage(
    state: &AdminState,
    workspace_id: WorkspaceId,
    project_id: ProjectId,
    workstream_ids: &[String],
    operation: &'static str,
) -> (Vec<String>, Vec<String>) {
    let project_root = state.wiki.project_root(workspace_id, project_id);
    let project_root_display = project_root.display().to_string();
    let mut deleted = Vec::with_capacity(workstream_ids.len() + 1);
    let mut failed = Vec::new();

    match state
        .wiki
        .remove_project_dir(workspace_id, project_id)
        .await
    {
        Ok(()) => deleted.push(project_root_display.clone()),
        Err(error) => {
            warn!(
                operation,
                path = %project_root_display,
                error = %error,
                "project purge failed to remove wiki directory"
            );
            failed.push(project_root_display);
        }
    }

    let (raw_deleted, raw_failed) =
        remove_workstream_segment_storage(state, workstream_ids, operation).await;
    deleted.extend(raw_deleted);
    failed.extend(raw_failed);

    (deleted, failed)
}

async fn handle_purge_project(
    State(state): State<Arc<AdminState>>,
    actor_ext: Option<axum::Extension<ai_memory_core::ActorContext>>,
    author_ext: Option<axum::Extension<ai_memory_core::UserId>>,
    Json(req): Json<PurgeProjectRequest>,
) -> impl IntoResponse {
    let author_id = author_ext.map(|axum::Extension(u)| u);
    // `dry_run` always wins, exactly like `reclaim-ledger-versions` (its
    // handler passes `req.dry_run` straight into the op regardless of any
    // other field): `{"confirm": true, "dry_run": true}` must never run the
    // destructive path just because `confirm` also happened to be set.
    if req.dry_run {
        return purge_project_preview(&state, &req, author_id).await;
    }
    if !req.confirm {
        return (
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "error": "destructive operation requires confirm=true"
            })),
        );
    }

    // Look up workspace and project IDs without auto-creating.
    let (ws_id, proj_id, project_name) = match resolve_target_for_admin(
        &state,
        &req.workspace,
        req.project.as_deref(),
        req.project_id.as_deref(),
    )
    .await
    {
        Ok(target) => target,
        Err(e) => return e,
    };

    let label = format!("{}/{}", req.workspace, project_name);

    // Admission must run before any destructive work. A reject-policy webhook
    // is allowed to abort the purge while DB rows and files are still intact.
    // Seed names from the request so mirrors do not depend on DB lookup after
    // the rows are purged below. Carry the authenticated actor so a scope-guard
    // admission webhook can authorize the purge by user — an empty actor is
    // rejected (`403 user '' not allowed to purge_project`).
    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: project_name.clone(),
        op: AdmissionOp::PurgeProject,
        actor,
        ..Default::default()
    };
    let resolved_purge_ctx = match state
        .wiki
        .admit_purge_project(ws_id, proj_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-purge-project {label}"))
    {
        Ok(oid) => oid,
        Err(e) => return e,
    };

    let compaction = if req.compact {
        ai_memory_store::Compaction::Reclaim
    } else {
        ai_memory_store::Compaction::Skip
    };

    let summary = match state
        .writer
        .purge_project(
            ws_id,
            proj_id,
            &label,
            author_id,
            req.force,
            compaction,
            ai_memory_store::PurgeMode::Commit,
        )
        .await
    {
        Ok(s) => s,
        // A live managed run is a conflict, not a server fault: the operator
        // can finish the session or retry with `force`. Same status the
        // heartbeat itself returns when a lease is gone, so the two agree.
        Err(e @ StoreError::ManagedRunActive { .. }) => {
            return (
                StatusCode::CONFLICT,
                Json(serde_json::json!({ "error": e.to_string() })),
            );
        }
        Err(e) => return internal_err(e.to_string()),
    };

    // DB cascade already deleted all rows. Remove both the wiki project root
    // and every raw managed-workstream segment directory best-effort, reporting
    // partial failures without disguising the committed database purge.
    let (files_deleted, files_failed) = remove_purged_project_storage(
        &state,
        ws_id,
        proj_id,
        &summary.workstream_ids,
        "purge-project",
    )
    .await;
    // Mirrors that track filesystem reality (a git-push mirror) want to
    // know the on-disk dir is still present even though the DB rows are
    // gone, so they can refuse to drop their own copy in violation of
    // their source of truth. Mirrors that track DB intent can ignore
    // `partial_failure`. Default-skipped on the wire so existing
    // webhook consumers see no extra key.
    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(dispatch_ctx.as_ref());

    state.active_project.clear_project(proj_id);
    invalidate_scope_cache(&state, ScopeInvalidation::Project(proj_id)).await;

    let checkpoint = checkpoint_or_warn(&state.wiki, format!("purge-project {label}"));

    let report = PurgeProjectReport {
        label: summary.label,
        pages_deleted: summary.pages_deleted,
        sessions_deleted: summary.sessions_deleted,
        observations_deleted: summary.observations_deleted,
        handoffs_deleted: summary.handoffs_deleted,
        embeddings_deleted: summary.embeddings_deleted,
        collateral_observations_deleted: summary.collateral_observations_deleted,
        collateral_handoffs_denulled: summary.collateral_handoffs_denulled,
        workstreams_deleted: summary.workstreams_deleted,
        managed_runs_deleted: summary.managed_runs_deleted,
        workstream_ids: summary.workstream_ids,
        compacted: summary.compacted,
        files_deleted,
        files_failed,
        pre_checkpoint,
        checkpoint,
        dry_run: false,
    };

    (
        StatusCode::OK,
        Json(serde_json::to_value(&report).unwrap_or_else(|_| serde_json::json!({}))),
    )
}

/// Preview branch of `POST /admin/purge-project`: reached whenever `dry_run`
/// is true, regardless of `confirm` (see the `dry_run`-always-wins check in
/// `handle_purge_project`). `ai_memory_store::purge_project` under
/// `PurgeMode::Preview` counts every row a confirmed purge would delete —
/// via the same `SELECT`s the confirmed path itself uses to decide what to
/// delete, not a separately-maintained estimate — and returns without ever
/// issuing the `DELETE`, so there is no cascade to roll back, unlike
/// `move-session`'s dry run (which does run its write and rolls it back: a
/// session's rows are cheap; a whole project's are not, and this preview is
/// now the default no-`--confirm` behavior of a command a hook can also
/// race against).
///
/// Deliberately skipped, unlike the confirmed path above: it never opens the
/// blocking admission call (`admit_purge_project`) at all — nothing was
/// decided yet, so there is nothing for a mirror to act on — plus wiki file
/// removal (nothing was deleted) and both checkpoints (the git tree does not
/// change). Because admission never runs, a `200` here is not a guarantee:
/// a `Reject`-policy or scope-guard admission webhook only runs on the
/// confirmed path and can still refuse the real purge afterward.
///
/// Because admission never runs here, a `200` preview is not a promise the
/// confirmed purge will succeed: a `Reject`-policy or scope-guard admission
/// webhook only runs on the confirmed path and can still refuse it after the
/// operator has already seen this preview.
///
/// Scope resolution and its 404 run exactly as the real purge's do, so an
/// unknown workspace/project answers identically either way.
async fn purge_project_preview(
    state: &Arc<AdminState>,
    req: &PurgeProjectRequest,
    author_id: Option<ai_memory_core::UserId>,
) -> (StatusCode, Json<serde_json::Value>) {
    let (ws_id, proj_id, project_name) = match resolve_target_for_admin(
        state,
        &req.workspace,
        req.project.as_deref(),
        req.project_id.as_deref(),
    )
    .await
    {
        Ok(target) => target,
        Err(e) => return e,
    };

    let label = format!("{}/{}", req.workspace, project_name);

    let summary = match state
        .writer
        .purge_project(
            ws_id,
            proj_id,
            &label,
            author_id,
            req.force,
            // A preview never deletes anything, so there is nothing to
            // reclaim; `ops::purge_project` also forces `compacted: false`
            // for `PurgeMode::Preview` regardless of this value.
            ai_memory_store::Compaction::Skip,
            ai_memory_store::PurgeMode::Preview,
        )
        .await
    {
        Ok(s) => s,
        // Same conflict a confirmed purge would hit, reported the same way:
        // the preview is a promise of what a real purge would do, and a real
        // purge would refuse here too.
        Err(e @ StoreError::ManagedRunActive { .. }) => {
            return (
                StatusCode::CONFLICT,
                Json(serde_json::json!({ "error": e.to_string() })),
            );
        }
        Err(e) => return internal_err(e.to_string()),
    };

    let report = PurgeProjectReport {
        label: summary.label,
        pages_deleted: summary.pages_deleted,
        sessions_deleted: summary.sessions_deleted,
        observations_deleted: summary.observations_deleted,
        handoffs_deleted: summary.handoffs_deleted,
        embeddings_deleted: summary.embeddings_deleted,
        collateral_observations_deleted: summary.collateral_observations_deleted,
        collateral_handoffs_denulled: summary.collateral_handoffs_denulled,
        workstreams_deleted: summary.workstreams_deleted,
        managed_runs_deleted: summary.managed_runs_deleted,
        workstream_ids: summary.workstream_ids,
        compacted: false,
        files_deleted: Vec::new(),
        files_failed: Vec::new(),
        pre_checkpoint: None,
        checkpoint: None,
        dry_run: true,
    };

    (
        StatusCode::OK,
        Json(serde_json::to_value(&report).unwrap_or_else(|_| serde_json::json!({}))),
    )
}

// ---------------------------------------------------------------------
// rename-project
// ---------------------------------------------------------------------

/// JSON request body for `POST /admin/rename-workspace`.
#[derive(Deserialize)]
struct RenameWorkspaceRequest {
    /// Current workspace name (must exist).
    from: String,
    /// New workspace name. Must be non-empty, no slashes, and not already used.
    to: String,
}

/// Wire-format summary returned by `POST /admin/rename-workspace`.
#[derive(Debug, Serialize)]
pub struct RenameWorkspaceResult {
    /// Previous workspace name.
    pub from: String,
    /// New workspace name.
    pub to: String,
    /// 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,
    /// Non-fatal manifest refresh failure after the SQLite rename committed.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub manifest_warning: Option<String>,
}

/// `POST /admin/rename-workspace` — rename a workspace (column-only; the
/// on-disk dir is UUID-keyed, so nothing moves). 404 unknown, 422 taken/invalid.
async fn handle_rename_workspace(
    State(state): State<Arc<AdminState>>,
    Json(req): Json<RenameWorkspaceRequest>,
) -> impl IntoResponse {
    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 {
            StoreError::WorkspaceNameTaken(_) | StoreError::InvalidWorkspaceName(_) => {
                StatusCode::UNPROCESSABLE_ENTITY
            }
            StoreError::NotFound(_) => StatusCode::NOT_FOUND,
            _ => StatusCode::INTERNAL_SERVER_ERROR,
        };
        return (status, Json(serde_json::json!({ "error": e.to_string() })));
    }
    let (manifests_refreshed, manifest_warning) = match state.wiki.backfill_scope_manifests().await
    {
        Ok(n) => (n, None),
        Err(e) => {
            warn!(error = %e, "rename-workspace: scope-manifest backfill failed after rename");
            (0, Some(e.to_string()))
        }
    };
    invalidate_scope_cache(&state, ScopeInvalidation::Workspace(ws_id)).await;
    let checkpoint = checkpoint_or_warn(
        &state.wiki,
        format!("rename-workspace {} -> {}", req.from, req.to),
    );
    let result = RenameWorkspaceResult {
        from: req.from.clone(),
        to: req.to.clone(),
        checkpoint,
        manifests_refreshed,
        manifest_warning,
    };
    (
        StatusCode::OK,
        Json(serde_json::to_value(&result).unwrap_or(serde_json::Value::Null)),
    )
}

/// JSON request body for `POST /admin/delete-workspace`.
#[derive(Deserialize)]
struct DeleteWorkspaceRequest {
    /// Workspace name to delete (must exist).
    workspace: String,
    /// Delete even when the workspace still holds projects. Without it, a
    /// non-empty workspace is refused so a typo can't wipe live data.
    #[serde(default)]
    force: bool,
    /// Reclaim freed bytes: rebuild the FTS indexes and `VACUUM` after the
    /// delete commits. Off by default; see `ai_memory_store::Compaction` for
    /// the cost and for what it does not guarantee.
    #[serde(default)]
    compact: bool,
    /// Preview only: report the counts a delete of this workspace would
    /// produce without deleting anything. Wins over `force` in the sense
    /// that matters — `{"force": true, "dry_run": true}` still only
    /// previews, exactly like `purge-project` treats its own `dry_run` field,
    /// so a preview request can never accidentally become destructive.
    /// `#[serde(default)]` here is what keeps an *old* caller (built before
    /// this field existed, so it never sends `dry_run` at all) parsing the
    /// same request it always sent.
    #[serde(default)]
    dry_run: bool,
}

/// Wire-format summary returned by `POST /admin/delete-workspace`.
#[derive(Debug, Serialize)]
pub struct DeleteWorkspaceResult {
    /// Workspace name that was deleted.
    pub workspace: String,
    /// Projects removed via the `workspace_id` cascade.
    pub projects_deleted: u64,
    /// `pages` rows removed via cascade (all versions).
    pub pages_deleted: u64,
    /// `sessions` rows removed via cascade.
    pub sessions_deleted: u64,
    /// `observations` rows removed via cascade.
    pub observations_deleted: u64,
    /// `handoffs` rows removed via cascade.
    pub handoffs_deleted: u64,
    /// `page_embeddings` rows removed via cascade.
    pub embeddings_deleted: u64,
    /// `observations` rows in a **different** workspace, deleted collaterally
    /// because their `session_id` belongs to a session that lived in this one
    /// (`observations.session_id` is `ON DELETE CASCADE`, without regard to
    /// the observation's own `workspace_id`) — the mirror of the incident
    /// `purge-project`'s preview guards against, one level up. Always
    /// present, zero when there is none, so a caller can tell "no collateral
    /// damage" apart from "field absent on an older server".
    pub collateral_observations_deleted: u64,
    /// `handoffs` rows in a different workspace whose `from_session_id` or
    /// `accepted_by_session` is set to `NULL` (not deleted — those columns
    /// are `ON DELETE SET NULL`) because they referenced a session that lived
    /// in this workspace.
    pub collateral_handoffs_denulled: u64,
    /// Managed `workstreams` rows removed via cascade.
    pub workstreams_deleted: u64,
    /// `managed_runs` rows removed via cascade.
    pub managed_runs_deleted: u64,
    /// Ids of the deleted workstreams whose raw segment directories were
    /// included in the post-commit cleanup.
    pub workstream_ids: Vec<String>,
    /// Paths removed from disk (the workspace directory and raw segments).
    pub files_deleted: Vec<String>,
    /// Paths that could not be removed from disk (non-fatal; DB rows are gone).
    pub files_failed: Vec<String>,
    /// Whether the freed bytes were reclaimed (`VACUUM` ran). False for a
    /// plain logical delete: the rows are gone from the API and from search,
    /// but their bytes stay in free pages until the file is next rewritten.
    pub compacted: bool,
    /// 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>,
    /// `true` for a preview: `dry_run: true` in the request always wins, so
    /// this is only ever `false` on a run that actually deleted rows. The
    /// counts above are read directly by the same queries a confirmed delete
    /// uses to decide what to remove — never by running the delete and
    /// rolling it back — so `files_deleted`/`files_failed` are always empty
    /// and `pre_checkpoint`/`checkpoint` always absent: no wiki directory was
    /// touched, no admission webhook ran, and no purge dispatch went out.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub dry_run: bool,
}

/// `POST /admin/delete-workspace` — remove a workspace and, via cascade, every
/// project/page under it. Guarded: refuses a non-empty workspace unless
/// `force` (a typo shouldn't wipe live data). Orphan-workspace cleanup.
/// JSON request body for `POST /admin/compact`.
#[derive(Deserialize)]
struct CompactRequest {
    /// Mandatory confirmation. Not because compaction destroys anything — it
    /// deletes nothing — but because it takes an exclusive lock and rewrites
    /// the whole database, so every write blocks until it finishes. That is an
    /// availability decision, and it should be deliberate. An omitted field
    /// reads as `false`, so the caller gets the 400 that says what to send
    /// instead of the extractor's bare 422.
    #[serde(default)]
    confirm: bool,
}

/// Wire-format summary returned by `POST /admin/compact`.
#[derive(Debug, Serialize)]
pub struct CompactReport {
    /// Database size in bytes before the rebuild + `VACUUM`.
    pub bytes_before: u64,
    /// Database size in bytes afterwards.
    pub bytes_after: u64,
    /// Bytes returned to the filesystem (saturating at zero).
    pub bytes_reclaimed: u64,
}

/// `POST /admin/compact` — rebuild the FTS indexes and `VACUUM`, deleting
/// nothing. The on-demand form of what the destructive commands offer as
/// `--compact`.
async fn handle_compact(
    State(state): State<Arc<AdminState>>,
    Json(req): Json<CompactRequest>,
) -> impl IntoResponse {
    if !req.confirm {
        return (
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "error": "compact rewrites the whole database under an exclusive \
                          lock; pass confirm: true to proceed"
            })),
        );
    }
    match state.writer.compact().await {
        Ok(summary) => {
            let report = CompactReport {
                bytes_before: summary.bytes_before,
                bytes_after: summary.bytes_after,
                bytes_reclaimed: summary.bytes_reclaimed(),
            };
            (
                StatusCode::OK,
                Json(serde_json::to_value(&report).unwrap_or_else(|_| serde_json::json!({}))),
            )
        }
        Err(e) => (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(serde_json::json!({ "error": e.to_string() })),
        ),
    }
}

/// JSON request body for `POST /admin/reclaim-ledger-versions`.
#[derive(Deserialize)]
struct ReclaimLedgerVersionsRequest {
    /// Mandatory for a run that deletes. This one removes rows, and unlike
    /// `compact` it is not reversible by re-running anything: the bytes are
    /// only in the markdown the ledger mirrors, and only if the file on disk
    /// still holds them.
    #[serde(default)]
    confirm: bool,
    /// Report what would go without deleting it. A dry run changes nothing,
    /// so it needs no `confirm` — that is the whole point of it.
    #[serde(default)]
    dry_run: bool,
    /// Also drop each ledger's live row, not just its superseded versions.
    #[serde(default)]
    drop_latest: bool,
    /// Rebuild the FTS index and `VACUUM` afterwards to return the bytes.
    #[serde(default)]
    compact: bool,
}

/// Wire-format summary returned by `POST /admin/reclaim-ledger-versions`.
#[derive(Debug, Serialize)]
pub struct ReclaimLedgerVersionsReport {
    /// Ledger `(workspace, project, path)` coordinates holding residue.
    pub ledger_paths: u64,
    /// `pages` rows selected — removed, unless the run was a dry run.
    pub pages_deleted: u64,
    /// Bytes of page body those rows carried. Logical payload, not freed
    /// bytes: the file only shrinks when `compact` was set.
    pub bytes_deleted: u64,
    /// Bytes returned to the filesystem. Zero unless `compact` was set.
    pub bytes_reclaimed: u64,
    /// Whether each ledger's live row went too.
    pub dropped_latest: bool,
    /// Database size in bytes before the delete.
    pub bytes_before: u64,
    /// Database size in bytes afterwards.
    pub bytes_after: u64,
    /// Whether the freed bytes were reclaimed (`VACUUM` ran).
    pub compacted: bool,
}

/// `POST /admin/reclaim-ledger-versions` — delete the superseded versions of
/// the raw hook event ledger, and nothing else. The online counterpart of the
/// cleanup #660's fix left no command for.
async fn handle_reclaim_ledger_versions(
    State(state): State<Arc<AdminState>>,
    Json(req): Json<ReclaimLedgerVersionsRequest>,
) -> impl IntoResponse {
    if !req.dry_run && !req.confirm {
        return (
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "error": "reclaim-ledger-versions deletes page rows; \
                          run it without --confirm first to see what it would \
                          remove, then pass confirm: true"
            })),
        );
    }
    let compaction = if req.compact {
        ai_memory_store::Compaction::Reclaim
    } else {
        ai_memory_store::Compaction::Skip
    };
    match state
        .writer
        .reclaim_ledger_versions(req.dry_run, req.drop_latest, compaction)
        .await
    {
        Ok(summary) => {
            let report = ReclaimLedgerVersionsReport {
                ledger_paths: summary.ledger_paths,
                pages_deleted: summary.pages_deleted,
                bytes_deleted: summary.bytes_deleted,
                bytes_reclaimed: summary.bytes_reclaimed(),
                dropped_latest: summary.dropped_latest,
                bytes_before: summary.bytes_before,
                bytes_after: summary.bytes_after,
                compacted: summary.compacted,
            };
            (
                StatusCode::OK,
                Json(serde_json::to_value(&report).unwrap_or_else(|_| serde_json::json!({}))),
            )
        }
        Err(e) => (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(serde_json::json!({ "error": e.to_string() })),
        ),
    }
}

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 {
    // `dry_run` always wins, exactly like `purge-project` (its handler checks
    // `req.dry_run` before anything else regardless of any other field): a
    // caller must never be able to combine `dry_run: true` with `force: true`
    // and get a real delete.
    if req.dry_run {
        return delete_workspace_preview(&state, &req.workspace, req.force).await;
    }
    let actor = actor_ext
        .map(|axum::Extension(a)| a)
        .unwrap_or_else(ai_memory_core::ActorContext::anonymous);
    let compaction = if req.compact {
        ai_memory_store::Compaction::Reclaim
    } else {
        ai_memory_store::Compaction::Skip
    };
    match delete_workspace_core(&state, &req.workspace, req.force, actor, compaction).await {
        Ok(result) => (
            StatusCode::OK,
            Json(serde_json::to_value(&result).unwrap_or(serde_json::Value::Null)),
        ),
        Err(resp) => resp,
    }
}

/// Delete a workspace and, via cascade, every project/page under it — returning
/// the summary as data (or the HTTP error a handler surfaces verbatim). Guarded:
/// refuses a non-empty workspace unless `force`. Shared by
/// `handle_delete_workspace` and `handle_merge_workspace` (which drains the
/// source workspace first, then deletes the now-empty shell with `force=false`).
async fn delete_workspace_core(
    state: &Arc<AdminState>,
    workspace: &str,
    force: bool,
    actor: ai_memory_core::ActorContext,
    compaction: ai_memory_store::Compaction,
) -> Result<DeleteWorkspaceResult, MoveErr> {
    let ws_id = lookup_ws_no_create(state, workspace).await?;

    if !force {
        match state
            .reader
            .list_projects_with_stats_for_workspace(workspace.to_string(), OPERATOR)
            .await
        {
            Ok(projects) if !projects.is_empty() => {
                return Err((
                    StatusCode::CONFLICT,
                    Json(serde_json::json!({
                        "error": StoreError::WorkspaceNotEmpty(projects.len() as u64).to_string()
                    })),
                ));
            }
            Ok(_) => {}
            Err(e) => return Err(internal_err(e.to_string())),
        }
    }

    let purge_ctx = AdmissionContext {
        workspace: workspace.to_string(),
        project: String::new(),
        op: AdmissionOp::PurgeWorkspace,
        actor,
        ..Default::default()
    };
    if let Err(error) = state.wiki.validate_workspace_tree(ws_id) {
        return Err(internal_err(error.to_string()));
    }
    let resolved_purge_ctx = match state
        .wiki
        .admit_purge_workspace(ws_id, Some(purge_ctx))
        .await
    {
        Ok(ctx) => ctx,
        Err(e) => return Err(internal_err(e.to_string())),
    };

    let pre_checkpoint =
        checkpoint_or_500(&state.wiki, format!("pre-delete-workspace {workspace}"))?;

    let summary = match state
        .writer
        .delete_workspace(ws_id, force, compaction, ai_memory_store::PurgeMode::Commit)
        .await
    {
        Ok(s) => s,
        Err(e) => {
            let status = match &e {
                StoreError::WorkspaceNotEmpty(_) => StatusCode::CONFLICT,
                StoreError::NotFound(_) => StatusCode::NOT_FOUND,
                _ => StatusCode::INTERNAL_SERVER_ERROR,
            };
            return Err((status, Json(serde_json::json!({ "error": e.to_string() }))));
        }
    };

    let ws_root_str = state
        .wiki
        .root()
        .join(ws_id.to_string())
        .display()
        .to_string();
    let mut files_deleted = Vec::with_capacity(summary.workstream_ids.len() + 1);
    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 = %workspace, path = %ws_root_str, "delete-workspace: on-disk dir removal failed");
            files_failed.push(ws_root_str);
        }
    }
    let (raw_deleted, raw_failed) =
        remove_workstream_segment_storage(state, &summary.workstream_ids, "delete-workspace").await;
    files_deleted.extend(raw_deleted);
    files_failed.extend(raw_failed);

    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(dispatch_ctx.as_ref());

    state.active_project.clear_workspace(ws_id);
    invalidate_scope_cache(state, ScopeInvalidation::Workspace(ws_id)).await;

    Ok(DeleteWorkspaceResult {
        workspace: workspace.to_string(),
        projects_deleted: summary.projects_deleted,
        pages_deleted: summary.pages_deleted,
        sessions_deleted: summary.sessions_deleted,
        observations_deleted: summary.observations_deleted,
        handoffs_deleted: summary.handoffs_deleted,
        embeddings_deleted: summary.embeddings_deleted,
        collateral_observations_deleted: summary.collateral_observations_deleted,
        collateral_handoffs_denulled: summary.collateral_handoffs_denulled,
        workstreams_deleted: summary.workstreams_deleted,
        managed_runs_deleted: summary.managed_runs_deleted,
        workstream_ids: summary.workstream_ids,
        compacted: summary.compacted,
        files_deleted,
        files_failed,
        pre_checkpoint,
        checkpoint: checkpoint_or_warn(&state.wiki, format!("delete-workspace {workspace}")),
        dry_run: false,
    })
}

/// Preview branch of `POST /admin/delete-workspace`: reached whenever
/// `dry_run` is true, regardless of `force`. `ai_memory_store::delete_workspace`
/// under `PurgeMode::Preview` counts every row a confirmed delete would remove
/// — via the same `SELECT`s the confirmed path itself uses to decide what to
/// delete, not a separately-maintained estimate — and returns without ever
/// issuing the `DELETE`, so there is no cascade to roll back.
///
/// Deliberately skipped, unlike [`delete_workspace_core`]: it never opens the
/// blocking admission call (`admit_purge_workspace`) at all — nothing was
/// decided yet, so there is nothing for a mirror to act on — plus on-disk
/// directory removal (nothing was deleted) and both checkpoints (the git tree
/// does not change). Because admission never runs, a `200` here is not a
/// guarantee: a `Reject`-policy or scope-guard admission webhook only runs on
/// the confirmed path and can still refuse the real delete afterward.
///
/// Scope resolution and the non-empty-workspace guard run exactly as the real
/// delete's do, so an unknown workspace (404) or a non-empty workspace
/// without `force` (409) answers identically either way.
async fn delete_workspace_preview(
    state: &Arc<AdminState>,
    workspace: &str,
    force: bool,
) -> (StatusCode, Json<serde_json::Value>) {
    let ws_id = match lookup_ws_no_create(state, workspace).await {
        Ok(id) => id,
        Err(e) => return e,
    };

    let summary = match state
        .writer
        .delete_workspace(
            ws_id,
            force,
            // A preview never deletes anything, so there is nothing to
            // reclaim; `ops::delete_workspace` also forces `compacted: false`
            // for `PurgeMode::Preview` regardless of this value.
            ai_memory_store::Compaction::Skip,
            ai_memory_store::PurgeMode::Preview,
        )
        .await
    {
        Ok(s) => s,
        // Same conflict a confirmed delete would hit, reported the same way:
        // the preview is a promise of what a real delete would do, and a real
        // delete would refuse here too.
        Err(e @ StoreError::WorkspaceNotEmpty(_)) => {
            return (
                StatusCode::CONFLICT,
                Json(serde_json::json!({
                    "error": format!(
                        "{e} (pass \"force\": true alongside \"dry_run\": true to preview a \
                         non-empty workspace)"
                    )
                })),
            );
        }
        // A race between the `lookup_ws_no_create` above and this call (the
        // workspace was deleted in between): the same 404 a confirmed delete
        // would give for the same race, rather than a 500 or a 200 full of
        // zeros.
        Err(e @ StoreError::NotFound(_)) => {
            return (
                StatusCode::NOT_FOUND,
                Json(serde_json::json!({ "error": e.to_string() })),
            );
        }
        Err(e) => return internal_err(e.to_string()),
    };

    let report = DeleteWorkspaceResult {
        workspace: workspace.to_string(),
        projects_deleted: summary.projects_deleted,
        pages_deleted: summary.pages_deleted,
        sessions_deleted: summary.sessions_deleted,
        observations_deleted: summary.observations_deleted,
        handoffs_deleted: summary.handoffs_deleted,
        embeddings_deleted: summary.embeddings_deleted,
        collateral_observations_deleted: summary.collateral_observations_deleted,
        collateral_handoffs_denulled: summary.collateral_handoffs_denulled,
        workstreams_deleted: summary.workstreams_deleted,
        managed_runs_deleted: summary.managed_runs_deleted,
        workstream_ids: summary.workstream_ids,
        compacted: false,
        files_deleted: Vec::new(),
        files_failed: Vec::new(),
        pre_checkpoint: None,
        checkpoint: None,
        dry_run: true,
    };

    (
        StatusCode::OK,
        Json(serde_json::to_value(&report).unwrap_or_else(|_| serde_json::json!({}))),
    )
}

/// JSON request body for `POST /admin/rename-project`.
#[derive(Deserialize)]
struct RenameProjectRequest {
    /// Workspace name (must exist; we don't auto-create on rename).
    workspace: String,
    /// Current project name. Mutually exclusive with `project_id`; the CLI
    /// sends whichever the operator chose and leaves the other `None`.
    /// (#1208)
    #[serde(default)]
    from: Option<String>,
    /// Project id (UUID string). Bypasses the name/legacy/canonical lookup
    /// and targets the row directly. Same contract as
    /// `PurgeProjectRequest::project_id`. (#1208)
    #[serde(default)]
    project_id: Option<String>,
    /// New project name. Must be non-empty, no slashes.
    to: String,
}

/// Wire-format summary returned by `POST /admin/rename-project`.
#[derive(Debug, Serialize)]
pub struct RenameProjectSummary {
    /// Workspace name.
    pub workspace: String,
    /// Previous project name.
    pub from: String,
    /// New project name.
    pub to: String,
    /// Number of `is_latest=1` pages now under the renamed project.
    /// No files move — this is purely an informational count.
    pub pages: u64,
    /// Post-rename checkpoint, if `_meta.md` changed.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub checkpoint: Option<String>,
    /// Non-fatal manifest/checkpoint failure after the database rename committed.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub manifest_warning: Option<String>,
}

async fn handle_rename_project(
    State(state): State<Arc<AdminState>>,
    author_ext: Option<axum::Extension<ai_memory_core::UserId>>,
    Json(req): Json<RenameProjectRequest>,
) -> impl IntoResponse {
    let author_id = author_ext.map(|axum::Extension(u)| u);
    // Look up workspace + source project; 404 if either is absent.
    let (ws_id, proj_id, project_name) = match resolve_target_for_admin(
        &state,
        &req.workspace,
        req.from.as_deref(),
        req.project_id.as_deref(),
    )
    .await
    {
        Ok(target) => target,
        Err(e) => return e,
    };

    // Step 3: execute the rename. The writer validates the name and
    // returns ProjectNameTaken / InvalidProjectName on conflicts. A
    // `NotFound` here signals a race — typically a concurrent
    // `purge-project` deleted the row between the lookup above and
    // this UPDATE. Map it to 404 so the caller sees an honest failure
    // instead of the previous false-200.
    if let Err(e) = state
        .writer
        .rename_project(ws_id, proj_id, req.to.clone(), author_id)
        .await
    {
        let status = match &e {
            StoreError::ProjectNameTaken(_) | StoreError::InvalidProjectName(_) => {
                StatusCode::UNPROCESSABLE_ENTITY
            }
            StoreError::NotFound(_) => StatusCode::NOT_FOUND,
            _ => StatusCode::INTERNAL_SERVER_ERROR,
        };
        return (status, Json(serde_json::json!({ "error": e.to_string() })));
    }

    // Step 4: count is_latest pages that now belong to the renamed project.
    // COUNT(*) always produces a row, so no optional() needed. We pass the
    // 16-byte project id as a plain &[u8] slice to avoid importing rusqlite
    // (not a direct dependency of this crate).
    let pid_bytes = *proj_id.as_bytes();
    let pages = match state
        .reader
        .with_conn(move |conn| {
            let n: i64 = conn.query_row(
                "SELECT COUNT(*) FROM pages WHERE project_id = ?1 AND is_latest = 1",
                [&pid_bytes[..]],
                |row| row.get(0),
            )?;
            Ok(u64::try_from(n).unwrap_or(0))
        })
        .await
    {
        Ok(n) => n,
        Err(e) => {
            return (
                StatusCode::INTERNAL_SERVER_ERROR,
                Json(serde_json::json!({ "error": e.to_string() })),
            );
        }
    };

    let (checkpoint, manifest_warning) = match state
        .wiki
        .refresh_renamed_scope(ws_id, proj_id)
        .await
    {
        Ok(checkpoint) => (checkpoint, None),
        Err(error) => {
            warn!(
                error = %error,
                workspace_id = %ws_id,
                project_id = %proj_id,
                "rename-project committed; manifest refresh/checkpoint failed; startup backfill can repair"
            );
            (None, Some(error.to_string()))
        }
    };
    let summary = RenameProjectSummary {
        workspace: req.workspace.clone(),
        from: project_name.clone(),
        to: req.to.clone(),
        pages,
        checkpoint,
        manifest_warning,
    };
    (
        StatusCode::OK,
        Json(serde_json::to_value(&summary).unwrap_or_else(|_| serde_json::json!({}))),
    )
}

// ---------------------------------------------------------------------
// merge-project / move-project
// ---------------------------------------------------------------------

#[derive(Deserialize)]
struct MergeProjectRequest {
    workspace: String,
    #[serde(default)]
    from: Option<String>,
    #[serde(default)]
    from_project_id: Option<String>,
    #[serde(default)]
    into: Option<String>,
    #[serde(default)]
    into_project_id: Option<String>,
    #[serde(default)]
    confirm: bool,
}

#[derive(Serialize)]
struct MergeProjectReport {
    from: String,
    into: String,
    dry_run: bool,
    page_versions: u64,
    sessions: u64,
    observations: u64,
    handoffs: u64,
    workstreams: u64,
    page_conflicts: u64,
    #[serde(skip_serializing_if = "Option::is_none")]
    checkpoint: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    manifest_warning: Option<String>,
}

async fn prepare_project_merge(
    state: &AdminState,
    workspace: &str,
    source_name: &str,
    source: ProjectId,
    target_name: &str,
    target: ProjectId,
    workspace_id: WorkspaceId,
) -> Result<Vec<MergeProjectFile>, MoveErr> {
    let summaries = state
        .reader
        .list_pages(workspace, source_name)
        .await
        .map_err(|error| internal_err(error.to_string()))?;
    let mut pages = Vec::with_capacity(summaries.len());
    for summary in summaries {
        let path = PagePath::new(summary.path.clone()).map_err(|error| {
            internal_err(format!(
                "invalid indexed page path '{}': {error}",
                summary.path
            ))
        })?;
        let source_meta = state
            .reader
            .page_meta(workspace, source_name, path.as_str())
            .await
            .map_err(|error| internal_err(error.to_string()))?
            .ok_or_else(|| {
                (
                    StatusCode::CONFLICT,
                    Json(serde_json::json!({
                        "error": "project pages changed while the merge was being prepared"
                    })),
                )
            })?;
        let target_page_id = state
            .reader
            .page_meta(workspace, target_name, path.as_str())
            .await
            .map_err(|error| internal_err(error.to_string()))?
            .map(|meta| meta.id);
        let source_label = format!("{workspace}/{source_name}");
        pages.push(
            state
                .wiki
                .prepare_project_merge_file(
                    workspace_id,
                    source,
                    target,
                    ai_memory_store::MergeProjectPage {
                        path,
                        source_page_id: source_meta.id,
                        target_page_id,
                        merged_page: None,
                    },
                    &source_label,
                )
                .map_err(|error| match error {
                    WikiError::Io(ref io) if io.kind() == std::io::ErrorKind::NotFound => (
                        StatusCode::CONFLICT,
                        Json(serde_json::json!({
                            "error": "project pages changed while the merge was being prepared"
                        })),
                    ),
                    _ => internal_err(error.to_string()),
                })?,
        );
    }
    Ok(pages)
}

async fn handle_merge_project(
    State(state): State<Arc<AdminState>>,
    actor_ext: Option<axum::Extension<ai_memory_core::ActorContext>>,
    Json(req): Json<MergeProjectRequest>,
) -> impl IntoResponse {
    let actor = actor_ext
        .map(|axum::Extension(actor)| actor)
        .unwrap_or_else(ai_memory_core::ActorContext::anonymous);
    let result: Result<MergeProjectReport, MoveErr> = async {
        let (source_ws, source, source_name) = resolve_target_for_admin(
            &state,
            &req.workspace,
            req.from.as_deref(),
            req.from_project_id.as_deref(),
        )
        .await?;
        let (target_ws, target, target_name) = resolve_target_for_admin(
            &state,
            &req.workspace,
            req.into.as_deref(),
            req.into_project_id.as_deref(),
        )
        .await?;
        if source_ws != target_ws {
            return Err((
                StatusCode::BAD_REQUEST,
                Json(serde_json::json!({"error": "projects must be in the same workspace"})),
            ));
        }
        if source == target {
            return Err((
                StatusCode::BAD_REQUEST,
                Json(serde_json::json!({"error": "source and target project must be different"})),
            ));
        }
        let pages = prepare_project_merge(
            &state,
            &req.workspace,
            &source_name,
            source,
            &target_name,
            target,
            source_ws,
        )
        .await?;
        let store_pages = pages.iter().map(|page| page.store.clone()).collect();
        let summary = if req.confirm {
            let admission = AdmissionContext {
                workspace: req.workspace.clone(),
                project: source_name.clone(),
                destination_workspace: Some(req.workspace.clone()),
                destination_project: Some(target_name.clone()),
                op: AdmissionOp::MoveProject,
                actor,
                ..Default::default()
            };
            state
                .wiki
                .merge_project(source_ws, source, target, pages, Some(admission))
                .await
                .map_err(|error| match error {
                    WikiError::Io(ref io) if io.kind() == std::io::ErrorKind::NotFound => (
                        StatusCode::CONFLICT,
                        Json(serde_json::json!({
                            "error": "project pages changed while the merge was committing"
                        })),
                    ),
                    WikiError::Store(StoreError::ManagedRunActive { .. })
                    | WikiError::Store(StoreError::ProjectSessionsOpen { .. })
                    | WikiError::Store(StoreError::Duplicate(_))
                    | WikiError::Store(StoreError::PagePathCollides { .. })
                    | WikiError::Store(StoreError::NotFound(_)) => (
                        StatusCode::CONFLICT,
                        Json(serde_json::json!({"error": error.to_string()})),
                    ),
                    _ => internal_err(error.to_string()),
                })?
        } else {
            state
                .writer
                .merge_project(source_ws, source, target, store_pages, false)
                .await
                .map_err(|error| match error {
                    StoreError::ManagedRunActive { .. }
                    | StoreError::ProjectSessionsOpen { .. }
                    | StoreError::Duplicate(_)
                    | StoreError::PagePathCollides { .. } => (
                        StatusCode::CONFLICT,
                        Json(serde_json::json!({"error": error.to_string()})),
                    ),
                    StoreError::NotFound(_) => (
                        StatusCode::NOT_FOUND,
                        Json(serde_json::json!({"error": error.to_string()})),
                    ),
                    _ => internal_err(error.to_string()),
                })?
        };
        let (checkpoint, manifest_warning) = if req.confirm {
            state.active_project.clear_project(source);
            invalidate_scope_cache(&state, ScopeInvalidation::Project(source)).await;
            let manifest_warning = state
                .wiki
                .backfill_scope_manifests()
                .await
                .err()
                .map(|error| {
                    warn!(%error, "merge-project: scope manifest refresh failed");
                    error.to_string()
                });
            (
                checkpoint_or_warn(
                    &state.wiki,
                    format!(
                        "merge-project {}/{} -> {}/{}",
                        req.workspace, source_name, req.workspace, target_name
                    ),
                ),
                manifest_warning,
            )
        } else {
            (None, None)
        };
        Ok(MergeProjectReport {
            from: format!("{}/{}", req.workspace, source_name),
            into: format!("{}/{}", req.workspace, target_name),
            dry_run: !req.confirm,
            page_versions: summary.page_versions,
            sessions: summary.sessions,
            observations: summary.observations,
            handoffs: summary.handoffs,
            workstreams: summary.workstreams,
            page_conflicts: summary.page_conflicts,
            checkpoint,
            manifest_warning,
        })
    }
    .await;
    match result {
        Ok(report) => (
            StatusCode::OK,
            Json(serde_json::to_value(report).unwrap_or_else(|_| serde_json::json!({}))),
        ),
        Err(error) => error,
    }
}

/// JSON request body for `POST /admin/move-project`.
#[derive(Deserialize)]
struct MoveProjectRequest {
    /// Source workspace. Must already exist; we 404 if absent.
    from_workspace: String,
    /// Project name to move. Must already exist in `from_workspace`; 404 if absent.
    /// Mutually exclusive with `project_id`; the CLI sends whichever the
    /// operator chose and leaves the other `None`. (#1208)
    #[serde(default)]
    project: Option<String>,
    /// Project id (UUID string) in the source workspace. Bypasses the
    /// name/legacy/canonical lookup and targets the row directly. (#1208)
    #[serde(default)]
    project_id: Option<String>,
    /// Destination workspace. Auto-created if absent.
    to_workspace: String,
    /// Mandatory confirmation flag. The move PURGES the source after
    /// copying, so without `confirm: true` the server returns 400.
    #[serde(default)]
    confirm: bool,
    /// Override the active-project guard. By default the server refuses (409)
    /// to move the project the hook router is currently writing to, since a
    /// live session's next observation would carry a stale workspace id.
    /// `force: true` proceeds anyway (still safe: the move republishes the
    /// active pointer and the (workspace_id, project_id) trigger makes any
    /// stale write fail cleanly rather than corrupt). It never overrides a
    /// live managed-workstream lease in the destructive copy-purge path.
    #[serde(default)]
    force: bool,
    /// Acknowledge that this move is a **copy+purge merge** rather than a
    /// true-move, and that the source project's history goes with it (#1713).
    /// The server picks the strategy from the destination; when it resolves to
    /// the merge path and this is absent, the move is refused with the record
    /// counts it would discard.
    #[serde(default)]
    allow_lossy_merge: bool,
    /// Policy for the copy-purge MERGE path when a source page's path already
    /// exists in the destination with DIFFERENT content. Ignored by true-move
    /// (no copy). Default `block` — the safe choice for a destructive op.
    #[serde(default)]
    on_conflict: OnConflict,
}

/// What to do when a merged page path collides with an existing destination
/// page of different content.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Default)]
#[serde(rename_all = "lowercase")]
enum OnConflict {
    /// Abort the whole move (source untouched), listing the conflicting paths.
    /// The operator resolves them or picks another policy explicitly.
    #[default]
    Block,
    /// The source page supersedes the destination page at the same path (the
    /// destination's prior version becomes history).
    Overwrite,
    /// Keep BOTH: the source page lands under a de-duplicated path
    /// (`<stem>-from-<src_workspace>.md`), reported in `conflicts`.
    Duplicate,
}

/// Wire-format report returned by `POST /admin/move-project`.
#[derive(Debug, Serialize)]
pub struct MoveProjectReport {
    /// `from_workspace/project` label.
    pub from: String,
    /// `to_workspace/project` label.
    pub to: String,
    /// `true` when the destination workspace already held a same-named
    /// project — the copy MERGED into it rather than creating a fresh one.
    pub merged_into_existing: bool,
    /// How the move was performed:
    /// - `"true-move"`: a lossless cross-workspace re-stamp (same `project_id`,
    ///   one SQL transaction + one dir rename). Used when the destination has
    ///   no same-named project. Sessions/observations/handoffs and the full
    ///   supersession history all survive; nothing is re-embedded.
    /// - `"copy-purge"`: the destination already held a same-named project, so
    ///   the source's latest pages were copied in and merged, then the source
    ///   purged. Only durable pages move; episodic rows are dropped.
    pub moved_via: &'static str,
    /// Number of latest pages copied into the destination (copy-purge) or
    /// re-stamped in place (true-move).
    pub pages_copied: u64,
    /// Managed workstreams re-stamped in place by a lossless true move.
    /// Copy-purge reports zero because it does not transfer managed history.
    pub workstreams_moved: u64,
    /// Source paths whose on-disk file could not be read (copy skipped).
    /// When non-empty the source is NOT purged so a fixed re-run is safe.
    pub pages_skipped: Vec<String>,
    /// Whether the source project was purged (only when every page copied).
    pub source_purged: bool,
    /// Source `pages` rows deleted by the purge (all versions).
    pub source_pages_deleted: u64,
    /// Source `sessions` rows deleted by the purge.
    pub source_sessions_deleted: u64,
    /// Source `observations` rows deleted by the purge.
    pub source_observations_deleted: u64,
    /// Source `handoffs` rows deleted by the purge.
    pub source_handoffs_deleted: u64,
    /// Source `page_embeddings` rows deleted by the purge.
    pub source_embeddings_deleted: u64,
    /// Source on-disk dirs removed.
    pub files_deleted: Vec<String>,
    /// Source on-disk dirs that could not be removed (non-fatal).
    pub files_failed: Vec<String>,
    /// Same-path conflicts in the copy-purge merge: a source page whose path
    /// already existed in the destination (with different content) was landed
    /// under a de-duplicated path so BOTH survive. Each entry is the original
    /// source path and the de-duplicated destination path it was written to.
    pub conflicts: Vec<PathConflict>,
    /// Pre-move checkpoint, if the tree had uncommitted changes.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub pre_checkpoint: Option<String>,
    /// Post-move checkpoint, if the move changed the tree.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub checkpoint: Option<String>,
    /// Non-fatal manifest/checkpoint failure after destination promotion committed.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub manifest_warning: Option<ai_memory_core::repository_identity::ManifestWarning>,
}

/// One same-path collision resolved by de-duplicating the source page's path.
#[derive(Debug, Serialize)]
pub struct PathConflict {
    /// The source page's original path (also the destination's existing path).
    pub path: String,
    /// The de-duplicated path the source page was written to instead.
    pub moved_to: String,
}

/// An error response from a move: the HTTP status + JSON body a handler would
/// have returned directly. The move core returns this as the `Err` arm so a
/// single move can be surfaced verbatim by `handle_move_project` or aggregated
/// by `handle_merge_workspace`.
type MoveErr = (StatusCode, Json<serde_json::Value>);

/// Lossless cross-workspace move: under the wiki mutation gate, rename the
/// project's on-disk dir to the destination workspace, then re-stamp its
/// `workspace_id` across every domain table (one transaction, same
/// `project_id`). The caller has already verified the destination has no
/// same-named project.
async fn true_move_project(
    state: &Arc<AdminState>,
    req: &MoveProjectRequest,
    project_name: &str,
    src_ws: WorkspaceId,
    src_proj: ProjectId,
    pre_checkpoint: Option<String>,
    actor: ai_memory_core::ActorContext,
) -> Result<MoveProjectReport, MoveErr> {
    // Ensure the destination workspace ROW exists (FK target for the
    // re-stamp) without creating a new project — the existing project_id is
    // what we move.
    let dst_ws = match state
        .writer
        .get_or_create_workspace(req.to_workspace.clone())
        .await
    {
        Ok(ws) => ws,
        Err(e) => return Err(internal_err(e.to_string())),
    };

    // A true move targets a FRESH destination, so its dir must not already
    // exist. Wiki::move_project_workspace repeats this check under the
    // exclusive mutation guard before it renames anything.
    state
        .wiki
        .validate_project_tree(src_ws, src_proj)
        .map_err(|error| internal_err(error.to_string()))?;
    state
        .wiki
        .validate_project_tree(dst_ws, src_proj)
        .map_err(|error| internal_err(error.to_string()))?;
    let dst_dir = state.wiki.project_root(dst_ws, src_proj);
    if dst_dir.exists() {
        return Err((
            StatusCode::CONFLICT,
            Json(serde_json::json!({
                "error": format!(
                    "destination dir already exists: {}; refusing true-move",
                    dst_dir.display()
                )
            })),
        ));
    }

    let move_ctx = AdmissionContext {
        workspace: req.from_workspace.clone(),
        project: project_name.to_string(),
        destination_workspace: Some(req.to_workspace.clone()),
        destination_project: Some(project_name.to_string()),
        op: AdmissionOp::MoveProject,
        actor,
        ..Default::default()
    };

    // Wiki owns the critical section: it runs move admission, renames the dir,
    // re-stamps SQLite, and rolls the dir back on SQL failure while normal page
    // writes/reindexes are blocked by the same process-local gate.
    let summary = match state
        .wiki
        .move_project_workspace(src_proj, src_ws, dst_ws, Some(move_ctx))
        .await
    {
        Ok(s) => s,
        Err(WikiError::Store(StoreError::NotFound(msg))) => {
            return Err((
                StatusCode::NOT_FOUND,
                Json(serde_json::json!({ "error": msg })),
            ));
        }
        Err(e @ WikiError::DestinationExists(_)) => {
            return Err((
                StatusCode::CONFLICT,
                Json(serde_json::json!({ "error": e.to_string() })),
            ));
        }
        Err(e) => {
            warn!(error = %e, "true-move: move aborted before completion");
            return Err(internal_err(format!("move aborted (nothing changed): {e}")));
        }
    };

    // Keep the in-process active-project pointer correct: the project_id is
    // unchanged, only its workspace moved. If a hook had published this project
    // as active, republish it under the destination workspace so the next event
    // resolves cleanly (rather than tripping the pairing trigger first).
    state
        .active_project
        .retarget_project_workspace(src_proj, dst_ws);
    // Proactively drop any stale per-cwd cache entry for the moved project.
    invalidate_scope_cache(state, ScopeInvalidation::Project(src_proj)).await;

    if let Err(e) = state.wiki.backfill_scope_manifests().await {
        warn!(error = %e, "true-move: scope-manifest backfill failed after move");
    }
    let checkpoint = checkpoint_or_warn(
        &state.wiki,
        format!(
            "move-project {}/{} -> {}/{}",
            req.from_workspace, project_name, req.to_workspace, project_name
        ),
    );

    let report = MoveProjectReport {
        from: format!("{}/{}", req.from_workspace, project_name),
        to: format!("{}/{}", req.to_workspace, project_name),
        merged_into_existing: false,
        moved_via: "true-move",
        pages_copied: summary.pages_moved,
        workstreams_moved: summary.workstreams_moved,
        pages_skipped: Vec::new(),
        // Nothing is purged in a true move — the source rows ARE the
        // destination rows, just re-stamped.
        source_purged: false,
        source_pages_deleted: 0,
        source_sessions_deleted: 0,
        source_observations_deleted: 0,
        source_handoffs_deleted: 0,
        source_embeddings_deleted: 0,
        files_deleted: Vec::new(),
        files_failed: Vec::new(),
        // A true move never copies pages, so it never has a path conflict.
        conflicts: Vec::new(),
        pre_checkpoint,
        checkpoint,
        manifest_warning: None,
    };
    Ok(report)
}

/// Token inserted between the original stem and the source-workspace
/// slug when copy-purge merges conflicting page paths
/// (`<stem>-from-<src_workspace>.md`). The literal also appears in
/// `docs/lifecycle-ops.md`; keep these two in sync.
const DEDUP_FROM_TOKEN: &str = "-from-";

/// Char allowlist for the source-workspace slug embedded in a deduped
/// destination path. ASCII alphanumeric plus `-` / `_` keeps the slug
/// safe inside a filesystem path component on every supported platform
/// (Windows treats `:`, `*`, `?`, `<`, `>`, `|` as illegal; Linux
/// tolerates more but UTF-8 mojibake in filenames is a maintenance
/// hazard). Everything else collapses to a single `-` separator,
/// preserving readability without introducing path-traversal vectors.
fn is_dedup_slug_char(c: char) -> bool {
    c.is_ascii_alphanumeric() || c == '-' || c == '_'
}

/// Pick a destination path that collides with neither an existing destination
/// page nor one already claimed in this run. Keeps the source page's stem and
/// appends `<DEDUP_FROM_TOKEN><src_workspace>` (then `-2`, `-3`, …). Used by
/// the copy-purge merge to keep BOTH pages when a path conflicts.
async fn dedup_dest_path(
    state: &AdminState,
    dst_ws: WorkspaceId,
    dst_proj: ProjectId,
    src_path: &str,
    src_workspace: &str,
    used: &std::collections::HashSet<String>,
) -> PagePath {
    let (stem, ext) = match src_path.rsplit_once('.') {
        Some((s, e)) => (s.to_string(), format!(".{e}")),
        None => (src_path.to_string(), String::new()),
    };
    let slug: String = src_workspace
        .chars()
        .map(|c| if is_dedup_slug_char(c) { c } else { '-' })
        .collect();
    let base = format!("{stem}{DEDUP_FROM_TOKEN}{slug}");
    let mut n = 0u32;
    loop {
        let cand = if n == 0 {
            format!("{base}{ext}")
        } else {
            format!("{base}-{n}{ext}")
        };
        let collides = used.contains(&cand)
            || matches!(
                state.reader.page_body_by_ids(dst_ws, dst_proj, &cand).await,
                Ok(Some(_))
            );
        if !collides && let Ok(p) = PagePath::new(cand) {
            return p;
        }
        n += 1;
    }
}

fn page_copy_differs(
    existing: &ai_memory_store::StoredPageBody,
    source: &Markdown,
    source_title: &str,
    source_tier: Tier,
    source_pinned: bool,
) -> bool {
    // Frontmatter comparison is modulo the per-version `generated.at`,
    // matching the store's own idempotency projection: two pages whose
    // only difference is WHEN they were written are the same content.
    // Comparing it raw made merge-conflict detection timing-flaky — the
    // same seeded page written across a second boundary 409'd as
    // "different content" (found via the copy_purge flake on Windows).
    let existing_frontmatter: serde_json::Value =
        serde_json::from_str(&existing.frontmatter_json).unwrap_or_default();
    existing.body != source.body
        || ai_memory_core::okf::strip_generated_at(&existing_frontmatter)
            != ai_memory_core::okf::strip_generated_at(&source.frontmatter)
        || existing.title != source_title
        || existing.tier != source_tier.as_str()
        || existing.pinned != source_pinned
}

#[cfg(test)]
mod page_copy_differs_tests {
    use super::*;

    fn stored(fm: serde_json::Value, body: &str) -> ai_memory_store::StoredPageBody {
        ai_memory_store::StoredPageBody {
            title: "T".into(),
            body: body.into(),
            frontmatter_json: fm.to_string(),
            tier: "semantic".into(),
            pinned: false,
        }
    }

    /// Two pages whose only difference is WHEN they were written are the
    /// same content — the projection matches the store's idempotency rule.
    #[test]
    fn generated_at_alone_is_not_a_conflict() {
        let existing = stored(
            serde_json::json!({"title": "T", "generated": {"by": "x", "at": "2026-09-01T00:00:00Z"}}),
            "same",
        );
        let source = Markdown {
            frontmatter: serde_json::json!({"title": "T", "generated": {"by": "x", "at": "2026-09-02T00:00:00Z"}}),
            body: "same".into(),
        };
        assert!(!page_copy_differs(
            &existing,
            &source,
            "T",
            Tier::Semantic,
            false
        ));
    }

    #[test]
    fn body_and_real_frontmatter_changes_still_conflict() {
        let existing = stored(serde_json::json!({"title": "T"}), "one");
        let body_diff = Markdown {
            frontmatter: serde_json::json!({"title": "T"}),
            body: "two".into(),
        };
        assert!(page_copy_differs(
            &existing,
            &body_diff,
            "T",
            Tier::Semantic,
            false
        ));
        let fm_diff = Markdown {
            frontmatter: serde_json::json!({"title": "T", "tags": ["x"]}),
            body: "one".into(),
        };
        assert!(page_copy_differs(
            &existing,
            &fm_diff,
            "T",
            Tier::Semantic,
            false
        ));
    }
}

async fn handle_move_project(
    State(state): State<Arc<AdminState>>,
    actor_ext: Option<axum::Extension<ai_memory_core::ActorContext>>,
    Json(req): Json<MoveProjectRequest>,
) -> impl IntoResponse {
    // Carry the authenticated actor into both legs (move admission + the
    // source-purge admission) so a scope-guard webhook authorizes by user.
    let actor = actor_ext
        .map(|axum::Extension(a)| a)
        .unwrap_or_else(ai_memory_core::ActorContext::anonymous);
    match move_project_core(&state, &req, actor).await {
        Ok(report) => (
            StatusCode::OK,
            Json(serde_json::to_value(&report).unwrap_or_else(|_| serde_json::json!({}))),
        ),
        Err(resp) => resp,
    }
}

/// Validate one move request, pick the true-move vs copy-purge path, and
/// execute it — returning the report as data (or the HTTP error a handler
/// surfaces verbatim). Shared by `handle_move_project` (one move) and
/// `handle_merge_workspace` (a move per source project).
async fn move_project_core(
    state: &Arc<AdminState>,
    req: &MoveProjectRequest,
    actor: ai_memory_core::ActorContext,
) -> Result<MoveProjectReport, MoveErr> {
    // Destructive: it purges the source after copying. Require confirm.
    if !req.confirm {
        return Err((
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "error": "destructive operation requires confirm=true"
            })),
        ));
    }

    // A same-workspace "move" would get-or-create the SAME project as both
    // source and destination, copy it onto itself, then purge it — data
    // loss. Reject; in-workspace renames go through rename-project.
    if req.from_workspace == req.to_workspace {
        return Err((
            StatusCode::UNPROCESSABLE_ENTITY,
            Json(serde_json::json!({
                "error": "from_workspace and to_workspace are identical; use rename-project instead"
            })),
        ));
    }

    // A private profile is found as `default/_profile.<user id>`; moving it to
    // another workspace would orphan it. (A workspace `_profile` may move with
    // its workspace: it lands in, or merges into, the target's own profile.)
    // Checked on the requested NAME first so a nonexistent profile project is
    // still refused as 422 rather than surfacing the lookup's 404.
    if let Some(name) = req.project.as_deref()
        && name.starts_with(ai_memory_core::profile::USER_PROFILE_PROJECT_PREFIX)
    {
        return Err((
            StatusCode::UNPROCESSABLE_ENTITY,
            Json(serde_json::json!({
                "error": "a private cross-project profile stays in the default workspace and cannot be moved"
            })),
        ));
    }

    // Resolve the SOURCE without auto-creating — 404 on a typo.
    let (src_ws, src_proj, project_name) = match resolve_target_for_admin(
        state,
        &req.from_workspace,
        req.project.as_deref(),
        req.project_id.as_deref(),
    )
    .await
    {
        Ok(target) => target,
        Err(e) => return Err(MoveErr::from(e)),
    };

    // Same guard on the RESOLVED name, so the `project_id` path (which has no
    // name to inspect up front) is refused identically.
    if project_name.starts_with(ai_memory_core::profile::USER_PROFILE_PROJECT_PREFIX) {
        return Err((
            StatusCode::UNPROCESSABLE_ENTITY,
            Json(serde_json::json!({
                "error": "a private cross-project profile stays in the default workspace and cannot be moved"
            })),
        ));
    }

    // Live-session guard: refuse to move the project the hook router is
    // currently writing to. A live session's next observation/log would carry
    // the now-stale workspace id (the (workspace_id, project_id) trigger would
    // make it fail, but the operator should consciously opt in). `force: true`
    // proceeds — safe because the move republishes the active pointer below.
    if !req.force && state.active_project.contains_project(src_proj) {
        return Err((
            StatusCode::CONFLICT,
            Json(serde_json::json!({
                "error": format!(
                    "{}/{} is the active session's project; a live move risks stale-cache writes. \
                     Re-run with force=true to proceed.",
                    req.from_workspace, project_name
                )
            })),
        ));
    }

    // Detect MERGE: does the destination workspace already hold a same-named
    // project? (find_workspace may be None when the dest ws doesn't exist yet.)
    let merged_into_existing =
        match lookup_existing_scope(&state.reader, &req.to_workspace, &project_name).await {
            Ok(_) => true,
            Err(error) if error.is_not_found() => false,
            Err(error) => return Err(scope_err(error)),
        };

    let pre_checkpoint = checkpoint_or_500(
        &state.wiki,
        format!(
            "pre-move-project {}/{} -> {}/{}",
            req.from_workspace, project_name, req.to_workspace, project_name
        ),
    )?;

    // FRESH destination (no same-named project there) → lossless TRUE MOVE.
    // Re-stamp the source project's workspace_id across every domain table in
    // one transaction (same project_id), then rename its on-disk dir. This
    // keeps sessions/observations/handoffs and the full supersession history,
    // and is O(1) instead of O(pages) — no per-page re-write, re-embed, or
    // admission webhook. The copy+purge path below is reserved for the MERGE
    // case, where two project_ids can't be re-stamped into one
    // (UNIQUE(workspace_id, name) collision).
    if !merged_into_existing {
        return true_move_project(
            state,
            req,
            &project_name,
            src_ws,
            src_proj,
            pre_checkpoint,
            actor,
        )
        .await;
    }

    // MERGE: the destination already holds a same-named project. Get-or-create
    // it (auto-creating the destination workspace) and copy the source's
    // latest pages into it, then purge the source.
    //
    // That second half is not a move: the source's sessions, observations,
    // handoffs and older page versions are deleted, while a true-move keeps
    // them. A `--confirm` written for "move this project" does not say that,
    // so the merge path needs its own acknowledgement and shows the counts it
    // would discard (#1713).
    if !req.allow_lossy_merge {
        let counts = state
            .reader
            .project_record_counts(src_ws, src_proj)
            .await
            .map_err(|error| internal_err(error.to_string()))?;
        return Err((
            StatusCode::CONFLICT,
            Json(serde_json::json!({
                "error": format!(
                    "the destination workspace already holds a project named '{project_name}', so \
                     this move would be a copy+purge merge: it copies its {} latest page(s) into \
                     that project and deletes the source project with its {} session(s), {} \
                     observation(s) and {} handoff(s). A true-move keeps all of that; to merge, \
                     re-run with --allow-lossy-merge (allow_lossy_merge=true)",
                    counts.pages, counts.sessions, counts.observations, counts.handoffs,
                ),
                "strategy": "copy-purge",
                "discarded": {
                    "pages_copied": counts.pages,
                    "sessions": counts.sessions,
                    "observations": counts.observations,
                    "handoffs": counts.handoffs,
                },
            })),
        ));
    }
    let destination = create_ws_proj(state, &req.to_workspace, &project_name).await?;
    let (dst_ws, dst_proj) = destination.scope.as_tuple();

    let warning = destination.manifest_warning;
    copy_purge_merge(
        state,
        req,
        &project_name,
        src_ws,
        src_proj,
        dst_ws,
        dst_proj,
        pre_checkpoint,
        actor,
        warning.clone(),
    )
    .await
    .map_err(|error| with_manifest_warning(error, warning.as_ref()))
}

// ---------------------------------------------------------------------
// move-session
// ---------------------------------------------------------------------

/// JSON request body for `POST /admin/move-session`.
///
/// Two shapes share the route: a single move names `session_id`; a batch
/// names `from_project` (plus optional `from_workspace`) and moves every
/// session touching that scope (a `sessions` row there OR observations
/// stamped into it). Exactly one of the two must be present. A session whose
/// row already sits in the destination is re-homed: only its rows still
/// lying elsewhere move (`session_moved: false`).
#[derive(Deserialize)]
struct MoveSessionRequest {
    /// The session to move (single form).
    #[serde(default)]
    session_id: Option<SessionId>,
    /// Source workspace of the batch form. Defaults to `default`.
    #[serde(default)]
    from_workspace: Option<String>,
    /// Source project of the batch form: every session touching it moves.
    #[serde(default)]
    from_project: Option<String>,
    /// Destination workspace. Defaults to the source workspace.
    #[serde(default)]
    workspace: Option<String>,
    /// Destination project. Must already exist unless `create` is set.
    project: String,
    /// What happens to `sessions/<id>.md`: `move` (default) carries the page
    /// and its history along; `regenerate` retires it in the source so the
    /// next consolidation writes a fresh one in the destination.
    #[serde(default)]
    pages: PagesMode,
    /// Without `confirm: true` the server runs the move inside a rolled-back
    /// transaction and reports what would change (`dry_run: true`).
    #[serde(default)]
    confirm: bool,
    /// Skip the live-session guards: an open session (no session end
    /// recorded; not applied to a re-home, whose row does not move), a
    /// `pending`/`running` consolidation job, and, for the batch form, the
    /// hook router's active-project pointer.
    #[serde(default)]
    force: bool,
    /// Create the destination workspace/project when absent instead of 404.
    /// A dry run never creates: it reports `would_create_project: true` and
    /// the counts computed against an absent target.
    #[serde(default)]
    create: bool,
}

/// `workspace/project` pair as names, for report labels.
#[derive(Debug, Clone, Serialize)]
pub struct ScopeLabel {
    /// Workspace name.
    pub workspace: String,
    /// Project name.
    pub project: String,
}

/// Row counts of one session move; identical for the dry run.
#[derive(Debug, Clone, Serialize)]
pub struct MoveSessionCounts {
    /// `observations` rows re-stamped.
    pub observations: u64,
    /// `handoffs` rows (produced by the session) re-stamped.
    pub handoffs: u64,
    /// `session_consolidation_jobs` rows re-stamped.
    pub consolidation_jobs: u64,
    /// `auto_improve_runs` rows re-stamped.
    pub auto_improve_runs: u64,
    /// `auto_improve_scheduler_claims` rows re-stamped.
    pub auto_improve_claims: u64,
    /// `pages` versions of `sessions/<id>.md` re-stamped (`pages: move`).
    pub page_versions_moved: u64,
    /// `pages` rows of `sessions/<id>.md` retired (`pages: regenerate`).
    pub pages_regenerated: u64,
}

/// One scope a move gathers observations out of, for the operator's report.
#[derive(Debug, Serialize)]
pub struct MoveSessionScopeCount {
    /// Workspace name.
    pub workspace: String,
    /// Project name.
    pub project: String,
    /// Observations of the session currently stamped into that scope.
    pub observations: u64,
}

/// Wire-format report for one session in `POST /admin/move-session`.
#[derive(Debug, Serialize)]
pub struct MoveSessionReport {
    /// The moved session.
    pub session_id: String,
    /// `true` when nothing was written (no `confirm`).
    pub dry_run: bool,
    /// Whether the `sessions` row changed scope. `false` for a re-home: the
    /// row already sat in the destination and only stray rows (the counts
    /// below) were gathered into it.
    pub session_moved: bool,
    /// Dry run with `create` against a destination that does not exist yet:
    /// the confirm run will create it. Never set on a confirmed move.
    #[serde(skip_serializing_if = "std::ops::Not::not")]
    pub would_create_project: bool,
    /// Every scope holding observations of this session other than the
    /// destination, with counts. More than one entry — or one that is not
    /// `from` — means the move drains a project the caller did not name.
    /// Empty when everything already sits in the destination.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub source_scopes: Vec<MoveSessionScopeCount>,
    /// Scope the session came from.
    pub from: ScopeLabel,
    /// Scope the session now belongs to.
    pub to: ScopeLabel,
    /// Row counts.
    pub summary: MoveSessionCounts,
    /// What happened (or would happen) to `sessions/<id>.md`: `"moved"`,
    /// `"regenerated"`, `"already in destination"` (re-home whose page rows
    /// all sit in the destination), or `"none"` when the session has no page
    /// anywhere.
    pub page: &'static str,
    /// The session's recorded working directory, left untouched.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cwd: Option<String>,
    /// Set when `basename(cwd)` differs from the destination project name.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cwd_warning: Option<String>,
    /// Pre-move checkpoint, if the tree had uncommitted changes.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub pre_checkpoint: Option<String>,
    /// Post-move checkpoint, if the move changed the tree.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub checkpoint: Option<String>,
    /// Non-fatal manifest/checkpoint failure after destination promotion committed.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub manifest_warning: Option<ai_memory_core::repository_identity::ManifestWarning>,
}

/// Wire-format report for the batch form of `POST /admin/move-session`.
#[derive(Debug, Serialize)]
pub struct MoveSessionBatchReport {
    /// `true` when nothing was written (no `confirm`).
    pub dry_run: bool,
    /// Dry run with `create` against a destination that does not exist yet.
    #[serde(skip_serializing_if = "std::ops::Not::not")]
    pub would_create_project: bool,
    /// Source scope.
    pub from: ScopeLabel,
    /// Destination scope.
    pub to: ScopeLabel,
    /// Sessions touching the source scope (a `sessions` row there or at
    /// least one observation stamped into it).
    pub total: usize,
    /// Sessions moved or re-homed (or, for a dry run, that would be).
    pub moved: usize,
    /// One report per session, oldest first (row `started_at` or first
    /// observation in the source).
    pub sessions: Vec<MoveSessionReport>,
    /// Pre-move checkpoint, if the tree had uncommitted changes.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub pre_checkpoint: Option<String>,
    /// Post-move checkpoint, if the batch changed the tree.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub checkpoint: Option<String>,
    /// Non-fatal manifest/checkpoint failure after destination promotion committed.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub manifest_warning: Option<ai_memory_core::repository_identity::ManifestWarning>,
}

/// One session move, resolved and validated, before any guard runs.
struct MoveSessionPlan {
    session_id: SessionId,
    /// Scope the rows are gathered from: the session row's own scope in the
    /// single form, the batch source in the batch form (where the row may
    /// well sit elsewhere, even in `to`).
    from: (WorkspaceId, ProjectId),
    from_label: ScopeLabel,
    to: MoveTarget,
    to_label: ScopeLabel,
    /// Where the `sessions` row sits right now.
    row_scope: (WorkspaceId, ProjectId),
    cwd: Option<String>,
}

impl MoveSessionPlan {
    /// The row already sits in the destination: only stray rows move.
    fn is_rehome(&self) -> bool {
        self.to.existing() == Some(self.row_scope)
    }
}

/// The destination of a move: an existing scope, or (dry run with `create`
/// only) a scope that does not exist yet and would be created on confirm.
#[derive(Debug, Clone, PartialEq, Eq)]
enum MoveTarget {
    Existing {
        scope: (WorkspaceId, ProjectId),
        manifest_warning: Option<ai_memory_core::repository_identity::ManifestWarning>,
    },
    WouldCreate,
}

impl MoveTarget {
    fn existing(&self) -> Option<(WorkspaceId, ProjectId)> {
        match self {
            Self::Existing { scope, .. } => Some(*scope),
            Self::WouldCreate => None,
        }
    }

    fn manifest_warning(&self) -> Option<ai_memory_core::repository_identity::ManifestWarning> {
        match self {
            Self::Existing {
                manifest_warning, ..
            } => manifest_warning.clone(),
            Self::WouldCreate => None,
        }
    }
}

async fn handle_move_session(
    State(state): State<Arc<AdminState>>,
    actor_ext: Option<axum::Extension<ai_memory_core::ActorContext>>,
    author_ext: Option<axum::Extension<ai_memory_core::UserId>>,
    Json(req): Json<MoveSessionRequest>,
) -> Response {
    let actor = actor_ext
        .map(|axum::Extension(a)| a)
        .unwrap_or_else(ai_memory_core::ActorContext::anonymous);
    let author_id = author_ext.map(|axum::Extension(u)| u);
    match (req.session_id, req.from_project.as_deref()) {
        (Some(session_id), None) => {
            match move_single_session(&state, &req, session_id, author_id, actor).await {
                Ok(report) => (StatusCode::OK, Json(json_or_empty(&report))).into_response(),
                Err(resp) => resp.into_response(),
            }
        }
        (None, Some(from_project)) => {
            move_session_batch(&state, &req, from_project, author_id, actor).await
        }
        _ => (
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "error": "provide exactly one of session_id (single move) or from_project (batch)"
            })),
        )
            .into_response(),
    }
}

fn json_or_empty<T: Serialize>(value: &T) -> serde_json::Value {
    serde_json::to_value(value).unwrap_or_else(|_| serde_json::json!({}))
}

/// Best-effort names for a scope; ids stand in when a row vanished
/// underneath us (a concurrent purge), so a report is still produced.
async fn scope_label(state: &AdminState, ws: WorkspaceId, proj: ProjectId) -> ScopeLabel {
    let workspace = state
        .reader
        .workspace_name_by_id(ws)
        .await
        .ok()
        .flatten()
        .unwrap_or_else(|| ws.to_string());
    let project = state
        .reader
        .project_name_by_id(ws, proj)
        .await
        .ok()
        .flatten()
        .unwrap_or_else(|| proj.to_string());
    ScopeLabel { workspace, project }
}

/// Resolve the destination scope: existing only (404) unless `create`. A
/// dry run never writes, so with `create` and no `confirm` an absent
/// destination resolves to [`MoveTarget::WouldCreate`] instead of a row.
async fn resolve_move_session_target(
    state: &AdminState,
    workspace: &str,
    project: &str,
    create: bool,
    confirm: bool,
) -> Result<MoveTarget, MoveErr> {
    if create && confirm {
        return create_ws_proj(state, workspace, project)
            .await
            .map(|target| MoveTarget::Existing {
                scope: target.scope.as_tuple(),
                manifest_warning: target.manifest_warning,
            });
    }
    match lookup_existing_scope(&state.reader, workspace, project).await {
        Ok(scope) => Ok(MoveTarget::Existing {
            scope: scope.as_tuple(),
            manifest_warning: None,
        }),
        Err(e) if create && e.is_not_found() => Ok(MoveTarget::WouldCreate),
        Err(e) => Err(scope_err(e)),
    }
}

/// Dry-run counts of a move into a destination that does not exist yet:
/// nothing of the session can already be there, so every row keyed to it
/// moves, and the page rows are those of `from` (moved or retired per
/// `pages`). Read-only; the store never sees the absent target.
async fn preview_move_into_absent_target(
    reader: &ReaderPool,
    session_id: SessionId,
    from: (WorkspaceId, ProjectId),
    pages: PagesMode,
) -> Result<MoveSessionCounts, StoreError> {
    let rows = reader.session_dependent_rows(session_id, from).await?;
    let (page_versions_moved, pages_regenerated) = match pages {
        PagesMode::Move => (rows.page_versions, 0),
        PagesMode::Regenerate => (0, rows.page_latest),
    };
    Ok(MoveSessionCounts {
        observations: rows.observations,
        handoffs: rows.handoffs,
        consolidation_jobs: rows.consolidation_jobs,
        auto_improve_runs: rows.auto_improve_runs,
        auto_improve_claims: rows.auto_improve_claims,
        page_versions_moved,
        pages_regenerated,
    })
}

/// `(session still open, consolidation job pending or running)` for the
/// live-session guards.
async fn session_move_blockers(
    reader: &ReaderPool,
    session_id: SessionId,
) -> Result<(bool, bool), StoreError> {
    reader
        .with_conn(move |conn| {
            let open: bool = conn.query_row(
                "SELECT ended_at IS NULL FROM sessions WHERE id = ?1",
                [session_id.as_bytes().as_slice()],
                |row| row.get(0),
            )?;
            let pending: bool = conn.query_row(
                "SELECT EXISTS(SELECT 1 FROM session_consolidation_jobs \
                 WHERE session_id = ?1 AND state IN ('pending', 'running'))",
                [session_id.as_bytes().as_slice()],
                |row| row.get(0),
            )?;
            Ok((open, pending))
        })
        .await
}

/// `(session_id, row scope, cwd)` of every session touching a scope (a
/// `sessions` row there or observations stamped into it), oldest first. The
/// row scope may differ from the queried scope: that is the phantom-bucket
/// case the batch re-homes.
async fn list_scope_sessions(
    reader: &ReaderPool,
    workspace_id: WorkspaceId,
    project_id: ProjectId,
) -> Result<Vec<(SessionId, (WorkspaceId, ProjectId), Option<String>)>, StoreError> {
    let ids = reader
        .session_ids_touching_scope(workspace_id, project_id)
        .await?;
    let mut out = Vec::with_capacity(ids.len());
    for sid in ids {
        // Observations reference `sessions` (FK on), so a listed id always
        // has a row; a concurrent purge is the only way to lose it here.
        if let Some((ws, proj, cwd)) = reader.find_session_scope(sid).await? {
            out.push((sid, (ws, proj), cwd));
        }
    }
    Ok(out)
}

fn move_session_store_err(e: StoreError) -> MoveErr {
    match e {
        StoreError::NotFound(msg) => (
            StatusCode::NOT_FOUND,
            Json(serde_json::json!({ "error": msg })),
        ),
        e @ StoreError::PagePathTaken { .. } => (
            StatusCode::CONFLICT,
            Json(serde_json::json!({
                "error": format!(
                    "{e}; re-run with pages=regenerate or resolve the destination page first"
                )
            })),
        ),
        other => internal_err(other.to_string()),
    }
}

fn move_session_wiki_err(e: WikiError) -> MoveErr {
    match e {
        WikiError::Store(store_err) => move_session_store_err(store_err),
        e @ WikiError::DestinationPageExists(_) => (
            StatusCode::CONFLICT,
            Json(serde_json::json!({ "error": e.to_string() })),
        ),
        other => internal_err(format!("move-session aborted: {other}")),
    }
}

/// The session's cwd is historical truth and stays put; say so when the
/// hook router's basename heuristic would not map it to the destination.
fn move_session_cwd_warning(cwd: Option<&str>, to_project: &str) -> Option<String> {
    let cwd = cwd?;
    let base = std::path::Path::new(cwd).file_name()?.to_str()?;
    if base == to_project {
        return None;
    }
    Some(format!(
        "session cwd '{cwd}' resolves to project '{base}' by basename, not '{to_project}'; \
         the cwd was left as recorded. New sessions started there still land in '{base}' \
         unless a .ai-memory.toml marker pins project = \"{to_project}\"; with \
         [routing] mid_session = \"sticky\" the remaining events of this session follow it."
    ))
}

fn move_session_source_scopes(
    summary: &ai_memory_store::MoveSessionSummary,
) -> Vec<MoveSessionScopeCount> {
    summary
        .source_scopes
        .iter()
        .map(|scope| MoveSessionScopeCount {
            workspace: scope.workspace_name.clone(),
            project: scope.project_name.clone(),
            observations: scope.observations,
        })
        .collect()
}

fn move_session_counts(summary: &ai_memory_store::MoveSessionSummary) -> MoveSessionCounts {
    MoveSessionCounts {
        observations: summary.observations,
        handoffs: summary.handoffs,
        consolidation_jobs: summary.consolidation_jobs,
        auto_improve_runs: summary.auto_improve_runs,
        auto_improve_claims: summary.auto_improve_claims,
        page_versions_moved: summary.page_versions_moved,
        pages_regenerated: summary.pages_regenerated,
    }
}

fn move_session_page_label(
    pages: PagesMode,
    touched_rows: bool,
    touched_file: bool,
    already_in_target: bool,
) -> &'static str {
    match (pages, touched_rows || touched_file) {
        (_, false) if already_in_target => "already in destination",
        (_, false) => "none",
        (PagesMode::Move, true) => "moved",
        (PagesMode::Regenerate, true) => "regenerated",
    }
}

/// Guards, then the dry run or the real move of one planned session. The
/// caller wraps the call in the pre/post checkpoints so a batch takes one
/// pair, not one per session.
async fn move_planned_session(
    state: &Arc<AdminState>,
    req: &MoveSessionRequest,
    plan: MoveSessionPlan,
    author_id: Option<ai_memory_core::UserId>,
    actor: &ai_memory_core::ActorContext,
) -> Result<MoveSessionReport, MoveErr> {
    let sid = plan.session_id;
    let rehome = plan.is_rehome();

    // Live-session guards. An open session may still receive events, and a
    // queued consolidation would write the page under the old scope; both
    // are the operator's call with `force`. A re-home leaves the row where
    // it is, so an open session is no reason to refuse gathering its strays.
    let (open, pending_job) = session_move_blockers(&state.reader, sid)
        .await
        .map_err(|e| internal_err(e.to_string()))?;
    if !req.force {
        if open && !rehome {
            return Err((
                StatusCode::CONFLICT,
                Json(serde_json::json!({
                    "error": format!(
                        "session {sid} is still open (no session end recorded); \
                         finish it or force the move (--force / force: true)"
                    )
                })),
            ));
        }
        if pending_job {
            return Err((
                StatusCode::CONFLICT,
                Json(serde_json::json!({
                    "error": format!(
                        "session {sid} has a pending or running consolidation job; \
                         wait for it or force the move (--force / force: true)"
                    )
                })),
            ));
        }
    }

    state
        .wiki
        .validate_project_tree(plan.from.0, plan.from.1)
        .map_err(move_session_wiki_err)?;
    let cwd_warning = move_session_cwd_warning(plan.cwd.as_deref(), &plan.to_label.project);
    let file_name = format!("{sid}.md");
    let src_file = state
        .wiki
        .project_root(plan.from.0, plan.from.1)
        .join("sessions")
        .join(&file_name);

    // Dry run with `create` against an absent destination: nothing exists to
    // collide with, and the store cannot re-stamp into a scope that has no
    // row, so the counts come from a read-only preview.
    let manifest_warning = plan.to.manifest_warning();
    let to = match &plan.to {
        MoveTarget::Existing { scope, .. } => *scope,
        MoveTarget::WouldCreate => {
            debug_assert!(
                !req.confirm,
                "an absent target is only planned for a dry run"
            );
            let counts = preview_move_into_absent_target(&state.reader, sid, plan.from, req.pages)
                .await
                .map_err(|e| internal_err(e.to_string()))?;
            let touched_rows = counts.page_versions_moved > 0 || counts.pages_regenerated > 0;
            return Ok(MoveSessionReport {
                session_id: sid.to_string(),
                dry_run: true,
                session_moved: true,
                would_create_project: true,
                source_scopes: Vec::new(),
                from: plan.from_label,
                to: plan.to_label,
                page: move_session_page_label(req.pages, touched_rows, src_file.is_file(), false),
                summary: counts,
                cwd: plan.cwd,
                cwd_warning,
                pre_checkpoint: None,
                checkpoint: None,
                manifest_warning,
            });
        }
    };

    // A page file already at the destination blocks a page move; checked here
    // too so the dry run predicts what the wiki re-checks under its lock. When
    // the source scope IS the destination (single-form re-home) there is no
    // file to move and the wiki skips the file step too.
    state
        .wiki
        .validate_project_tree(to.0, to.1)
        .map_err(move_session_wiki_err)?;
    let dst_file = state
        .wiki
        .project_root(to.0, to.1)
        .join("sessions")
        .join(&file_name);
    let file_moves = plan.from != to && src_file.is_file();
    if req.pages == PagesMode::Move && file_moves && dst_file.exists() {
        return Err(move_session_wiki_err(WikiError::DestinationPageExists(
            dst_file.display().to_string(),
        )));
    }

    if !req.confirm {
        let summary = state
            .writer
            .move_session(sid, to.0, to.1, req.pages, author_id, false)
            .await
            .map_err(move_session_store_err)?;
        let touched_rows = summary.page_versions_moved > 0 || summary.pages_regenerated > 0;
        return Ok(MoveSessionReport {
            session_id: sid.to_string(),
            dry_run: true,
            session_moved: summary.session_moved,
            would_create_project: false,
            source_scopes: move_session_source_scopes(&summary),
            from: plan.from_label,
            to: plan.to_label,
            summary: move_session_counts(&summary),
            page: move_session_page_label(
                req.pages,
                touched_rows,
                file_moves,
                summary.page_versions_in_target > 0,
            ),
            cwd: plan.cwd,
            cwd_warning,
            pre_checkpoint: None,
            checkpoint: None,
            manifest_warning: manifest_warning.clone(),
        });
    }

    let move_ctx = AdmissionContext {
        workspace: plan.from_label.workspace.clone(),
        project: plan.from_label.project.clone(),
        destination_workspace: Some(plan.to_label.workspace.clone()),
        destination_project: Some(plan.to_label.project.clone()),
        op: AdmissionOp::MoveSession,
        actor: actor.clone(),
        ..Default::default()
    };
    // The wiki owns the critical section: admission, file move, SQL
    // re-stamp, and the file rollback on SQL failure.
    let outcome = state
        .wiki
        .move_session_page(sid, plan.from, to, req.pages, author_id, Some(move_ctx))
        .await
        .map_err(move_session_wiki_err)?;
    let touched_rows =
        outcome.summary.page_versions_moved > 0 || outcome.summary.pages_regenerated > 0;
    Ok(MoveSessionReport {
        session_id: sid.to_string(),
        dry_run: false,
        session_moved: outcome.summary.session_moved,
        would_create_project: false,
        source_scopes: move_session_source_scopes(&outcome.summary),
        from: plan.from_label,
        to: plan.to_label,
        summary: move_session_counts(&outcome.summary),
        page: move_session_page_label(
            req.pages,
            touched_rows,
            outcome.file != SessionPageFile::Absent,
            outcome.summary.page_versions_in_target > 0,
        ),
        cwd: plan.cwd,
        cwd_warning,
        pre_checkpoint: None,
        checkpoint: None,
        manifest_warning,
    })
}

async fn move_single_session(
    state: &Arc<AdminState>,
    req: &MoveSessionRequest,
    session_id: SessionId,
    author_id: Option<ai_memory_core::UserId>,
    actor: ai_memory_core::ActorContext,
) -> Result<MoveSessionReport, MoveErr> {
    let (from_ws, from_proj, cwd) = state
        .reader
        .find_session_scope(session_id)
        .await
        .map_err(|e| internal_err(e.to_string()))?
        .ok_or_else(|| {
            (
                StatusCode::NOT_FOUND,
                Json(serde_json::json!({ "error": format!("session {session_id} not found") })),
            )
        })?;
    let from_label = scope_label(state, from_ws, from_proj).await;
    let to_workspace = req
        .workspace
        .clone()
        .unwrap_or_else(|| from_label.workspace.clone());
    let to =
        resolve_move_session_target(state, &to_workspace, &req.project, req.create, req.confirm)
            .await?;
    let plan = MoveSessionPlan {
        session_id,
        from: (from_ws, from_proj),
        from_label,
        to,
        to_label: ScopeLabel {
            workspace: to_workspace,
            project: req.project.clone(),
        },
        row_scope: (from_ws, from_proj),
        cwd,
    };

    if !req.confirm {
        return move_planned_session(state, req, plan, author_id, &actor).await;
    }
    let label = format!(
        "move-session {session_id} {}/{} -> {}/{}",
        plan.from_label.workspace,
        plan.from_label.project,
        plan.to_label.workspace,
        plan.to_label.project
    );
    let warning = plan.to.manifest_warning();
    let pre_checkpoint = checkpoint_or_500(&state.wiki, format!("pre-{label}"))
        .map_err(|error| with_manifest_warning(error, warning.as_ref()))?;
    let mut report = move_planned_session(state, req, plan, author_id, &actor)
        .await
        .map_err(|error| with_manifest_warning(error, warning.as_ref()))?;
    if let Err(e) = state.wiki.backfill_scope_manifests().await {
        warn!(error = %e, "move-session: scope-manifest backfill failed after move");
    }
    report.pre_checkpoint = pre_checkpoint;
    report.checkpoint = checkpoint_or_warn(&state.wiki, label);
    Ok(report)
}

async fn move_session_batch(
    state: &Arc<AdminState>,
    req: &MoveSessionRequest,
    from_project: &str,
    author_id: Option<ai_memory_core::UserId>,
    actor: ai_memory_core::ActorContext,
) -> Response {
    let from_workspace = req
        .from_workspace
        .clone()
        .unwrap_or_else(|| DEFAULT_WORKSPACE_NAME.to_string());
    let from = match lookup_ws_proj_no_create(state, &from_workspace, from_project).await {
        Ok(ids) => ids,
        Err(e) => return e.into_response(),
    };
    let to_workspace = req
        .workspace
        .clone()
        .unwrap_or_else(|| from_workspace.clone());
    let to = match resolve_move_session_target(
        state,
        &to_workspace,
        &req.project,
        req.create,
        req.confirm,
    )
    .await
    {
        Ok(target) => target,
        Err(e) => return e.into_response(),
    };
    let from_label = ScopeLabel {
        workspace: from_workspace,
        project: from_project.to_string(),
    };
    let to_label = ScopeLabel {
        workspace: to_workspace,
        project: req.project.clone(),
    };
    let manifest_warning = to.manifest_warning();
    if to.existing() == Some(from) {
        return with_manifest_warning(
            (
                StatusCode::UNPROCESSABLE_ENTITY,
                Json(serde_json::json!({
                    "error": "source and destination scopes are identical"
                })),
            ),
            manifest_warning.as_ref(),
        )
        .into_response();
    }
    // Same guard as move-project: the project the hook router is writing to
    // is not emptied out from under it without an explicit `force`.
    if !req.force && state.active_project.contains_project(from.1) {
        return with_manifest_warning(
            (
                StatusCode::CONFLICT,
                Json(serde_json::json!({
                    "error": format!(
                        "{}/{} is the active session's project; force the move (--force / \
                         force: true) to move its sessions anyway",
                        from_label.workspace, from_label.project
                    )
                })),
            ),
            manifest_warning.as_ref(),
        )
        .into_response();
    }
    let sessions = match list_scope_sessions(&state.reader, from.0, from.1).await {
        Ok(v) => v,
        Err(e) => {
            return with_manifest_warning(internal_err(e.to_string()), manifest_warning.as_ref())
                .into_response();
        }
    };

    let label = format!(
        "move-session {}/{} -> {}/{}",
        from_label.workspace, from_label.project, to_label.workspace, to_label.project
    );
    let pre_checkpoint = if req.confirm && !sessions.is_empty() {
        match checkpoint_or_500(&state.wiki, format!("pre-{label}")) {
            Ok(oid) => oid,
            Err(e) => {
                return with_manifest_warning(e, manifest_warning.as_ref()).into_response();
            }
        }
    } else {
        None
    };

    let total = sessions.len();
    let mut reports = Vec::with_capacity(total);
    let mut failure: Option<(SessionId, MoveErr)> = None;
    for (session_id, row_scope, cwd) in sessions {
        // The page file follows the page rows: a session rooted in a third
        // scope (only some observations in the source) is moved whole from
        // where its row sits; a session already rooted in the destination is
        // re-homed and its stray page file, if any, is looked for in the
        // source.
        let (plan_from, plan_from_label) = if row_scope == from || to.existing() == Some(row_scope)
        {
            (from, from_label.clone())
        } else {
            (
                row_scope,
                scope_label(state, row_scope.0, row_scope.1).await,
            )
        };
        let plan = MoveSessionPlan {
            session_id,
            from: plan_from,
            from_label: plan_from_label,
            to: to.clone(),
            to_label: to_label.clone(),
            row_scope,
            cwd,
        };
        match move_planned_session(state, req, plan, author_id, &actor).await {
            Ok(report) => reports.push(report),
            Err(e) => {
                failure = Some((session_id, e));
                break;
            }
        }
    }

    let checkpoint = if req.confirm && !reports.is_empty() {
        if let Err(e) = state.wiki.backfill_scope_manifests().await {
            warn!(error = %e, "move-session: scope-manifest backfill failed after batch");
        }
        checkpoint_or_warn(&state.wiki, label)
    } else {
        None
    };

    // Stop at the first error, but say how far the batch got: the sessions
    // already moved stay moved (each was its own transaction).
    if let Some((session_id, (status, Json(mut body)))) = failure {
        if let Some(obj) = body.as_object_mut() {
            obj.insert(
                "session_id".into(),
                serde_json::json!(session_id.to_string()),
            );
            obj.insert("dry_run".into(), serde_json::json!(!req.confirm));
            obj.insert("total".into(), serde_json::json!(total));
            obj.insert("moved".into(), serde_json::json!(reports.len()));
            obj.insert("sessions".into(), json_or_empty(&reports));
            if let Some(oid) = checkpoint {
                obj.insert("checkpoint".into(), serde_json::json!(oid));
            }
            if let Some(warning) = manifest_warning.clone() {
                obj.insert("manifest_warning".into(), serde_json::json!(warning));
            }
        }
        return (status, Json(body)).into_response();
    }
    let report = MoveSessionBatchReport {
        dry_run: !req.confirm,
        would_create_project: to == MoveTarget::WouldCreate,
        from: from_label,
        to: to_label,
        total,
        moved: reports.len(),
        sessions: reports,
        pre_checkpoint,
        checkpoint,
        manifest_warning,
    };
    (StatusCode::OK, Json(json_or_empty(&report))).into_response()
}

/// One source page, with everything the copy loop and the block
/// pre-check both need. Built in ONE pass over the source listing so
/// the previous two-pass implementation's double-IO (pre-scan + copy
/// loop each calling `page_meta` + `page_body_by_ids` + `read_page`)
/// collapses to a single read per page.
struct PreparedSourcePage {
    path: PagePath,
    /// Path as a String — only needed for reports / `pages_skipped`
    /// and `dedup` lookups; kept here so we don't keep recomputing.
    path_str: String,
    title: String,
    tier: Tier,
    pinned: bool,
    /// `Some(md)` when the on-disk source survived parsing; `None` when
    /// reading or parsing failed and the page must be skipped (the
    /// safety guard at the end of the merge will refuse to purge).
    md: Option<Markdown>,
    /// `true` when the destination already holds this path with a
    /// DIFFERENT page (body / frontmatter / title / tier / pinned).
    /// `false` when there's no destination row, the destination
    /// matches verbatim (no-op supersession), or the source itself
    /// couldn't be parsed and we'd skip it anyway.
    dest_conflict: bool,
}

/// Load every source page (metadata + body) and pre-classify whether
/// its path collides with a different page at the destination. Both
/// the `Block` pre-check and the copy loop drive off the returned
/// vector, so each page is read at most once.
///
/// The argument list mirrors one prepared row: the request (for its
/// workspace name), the resolved `project_name` (which may differ from
/// `req.project` when the operator targeted `project_id` instead), the
/// source scope to read from, and the destination scope to compare
/// against. Splitting it into a struct would only move the same fields
/// one level down. (#1208)
#[allow(clippy::too_many_arguments)]
async fn prepare_source_pages(
    state: &AdminState,
    req: &MoveProjectRequest,
    project_name: &str,
    src_ws: WorkspaceId,
    src_proj: ProjectId,
    dst_ws: WorkspaceId,
    dst_proj: ProjectId,
    summaries: &[ai_memory_store::PageSummary],
) -> Vec<PreparedSourcePage> {
    let mut out = Vec::with_capacity(summaries.len());
    for s in summaries {
        let Ok(path) = PagePath::new(s.path.clone()) else {
            // Unparseable path — record a "skip" entry so the copy
            // loop can report it without re-trying the lookup.
            out.push(PreparedSourcePage {
                path: PagePath::new("invalid.md".to_string()).expect("valid placeholder"),
                path_str: s.path.clone(),
                title: s.title.clone(),
                tier: Tier::Semantic,
                pinned: false,
                md: None,
                dest_conflict: false,
            });
            continue;
        };
        let tier: Tier = s.tier.parse().unwrap_or(Tier::Semantic);
        let pinned = matches!(
            state
                .reader
                .page_meta(&req.from_workspace, project_name, &s.path)
                .await,
            Ok(Some(ref m)) if m.pinned
        );
        let md = state.wiki.read_page(src_ws, src_proj, &path).ok();
        // Compute the conflict decision once. The check is "is there a
        // DIFFERENT page at this path?", which requires both the dest
        // body and the source markdown — when either is missing, treat
        // as no-conflict and let the copy loop's natural-path branch
        // handle it (it'll either supersede a no-op or skip with a
        // missing-md guard).
        let dest_conflict = matches!(
            (
                state
                    .reader
                    .page_body_by_ids(dst_ws, dst_proj, s.path.as_str())
                    .await,
                &md,
            ),
            (Ok(Some(existing)), Some(md_ref))
                if page_copy_differs(&existing, md_ref, &s.title, tier, pinned)
        );
        out.push(PreparedSourcePage {
            path,
            path_str: s.path.clone(),
            title: s.title.clone(),
            tier,
            pinned,
            md,
            dest_conflict,
        });
    }
    out
}

/// Execute the copy-purge merge once the destination has been
/// resolved. Pulled out of `handle_move_project` so the orchestrator
/// reads as "validate → branch → copy_purge_merge", and the copy
/// loop's per-page IO runs through a pre-computed `PreparedSourcePage`
/// instead of fetching the same metadata twice.
// Merge-path orchestration: state + req + the four namespaced ids
// (src/dst ws+proj) + pre-checkpoint + the authenticated actor. Bundling
// the ids into a struct would obscure more than the arity warning, matching
// the existing `#[allow]`s on the equivalent store-layer helpers.
#[allow(clippy::too_many_arguments)]
async fn copy_purge_merge(
    state: &AdminState,
    req: &MoveProjectRequest,
    project_name: &str,
    src_ws: WorkspaceId,
    src_proj: ProjectId,
    dst_ws: WorkspaceId,
    dst_proj: ProjectId,
    pre_checkpoint: Option<String>,
    actor: ai_memory_core::ActorContext,
    manifest_warning: Option<ai_memory_core::repository_identity::ManifestWarning>,
) -> Result<MoveProjectReport, MoveErr> {
    // Enumerate the source's latest pages (authoritative on is_latest).
    let summaries = match state
        .reader
        .list_pages(&req.from_workspace, project_name)
        .await
    {
        Ok(s) => s,
        Err(e) => return Err(internal_err(e.to_string())),
    };

    // Single pass over the source: load each page's metadata + body
    // AND classify the destination conflict, so the block pre-check
    // and the copy loop don't re-query the same rows.
    let prepared = prepare_source_pages(
        state,
        req,
        project_name,
        src_ws,
        src_proj,
        dst_ws,
        dst_proj,
        &summaries,
    )
    .await;

    // Under the default `block` policy, abort the WHOLE move now —
    // before anything is copied — so the source stays intact and the
    // operator resolves the conflicts or re-runs with an explicit
    // overwrite/duplicate. Drives off the cached `dest_conflict_body`
    // computed by `prepare_source_pages`.
    if req.on_conflict == OnConflict::Block {
        let blocking: Vec<String> = prepared
            .iter()
            .filter(|p| p.dest_conflict)
            .map(|p| p.path_str.clone())
            .collect();
        if !blocking.is_empty() {
            return Err((
                StatusCode::CONFLICT,
                Json(serde_json::json!({
                    "error": "destination already has pages at these paths with different content; \
                              resolve them or re-run with on_conflict=overwrite or on_conflict=duplicate",
                    "conflicts": blocking,
                })),
            ));
        }
    }

    // Carry the source page embeddings over verbatim instead of recomputing
    // them — embedding is the dominant per-page cost of a bulk move. Writes go
    // through an embedder-less Wiki so `write_page` never re-embeds; we then
    // store each source vector against the new page id. Only embeddings
    // computed with the CURRENTLY configured embedder ({provider,model,dim})
    // are loaded (load_embeddings filters on them), so the "one model per
    // index" invariant holds; any page lacking a current-model embedding is
    // simply copied without one (backfill later via `ai-memory embed`).
    let copy_wiki = state.wiki.clone().without_embedder();
    let mut src_embeddings: std::collections::HashMap<String, Vec<u8>> =
        std::collections::HashMap::new();
    let embed_meta: Option<(String, String, u32)> = if let Some(embedder) = &state.embedder {
        // Not `.model()`: only vectors stored under the current document
        // identity are "current-model" for the carry-over below to load.
        // See `Embedder::model_identity`.
        let (provider, model, dim) = (
            embedder.provider().to_string(),
            embedder.model_identity(),
            embedder.dim(),
        );
        match state
            .reader
            .load_embeddings(src_ws, src_proj, provider.clone(), model.clone(), dim)
            .await
        {
            Ok(rows) => {
                for e in rows {
                    src_embeddings.insert(e.path.to_string(), f32_vec_to_bytes(&e.vector));
                }
                Some((provider, model, dim))
            }
            Err(e) => {
                warn!(error = %e, "move-project: failed to load source embeddings; copies land without vectors");
                None
            }
        }
    } else {
        None
    };

    // COPY each page through the (embedder-less) write path so sanitization,
    // link re-resolution, FTS upsert (and admission/git-mirror on deploy) all
    // fire — minus the per-page embed, which we carry over below. Drives off
    // the prebuilt `PreparedSourcePage` vec so each page is read at most
    // once across the whole merge (the previous version re-fetched in the
    // pre-scan + the copy loop for Block-policy callers).
    let mut pages_copied = 0u64;
    let mut pages_skipped: Vec<String> = Vec::new();
    let mut conflicts: Vec<PathConflict> = Vec::new();
    let mut used_dest_paths: std::collections::HashSet<String> = std::collections::HashSet::new();
    for p in prepared {
        let Some(md) = p.md else {
            // Either the path was unparseable or `read_page` failed —
            // either way we cannot copy it. The presence of a skip
            // here aborts the purge below.
            warn!(
                path = %p.path_str,
                "move-project: source page unreadable or invalid path; skipping"
            );
            pages_skipped.push(p.path_str.clone());
            continue;
        };
        // Apply the on_conflict policy using the cached classification.
        // `block` was already handled by the pre-scan above so we never
        // get here with `dest_conflict == true` AND `policy == Block`.
        let dest_path = if p.dest_conflict {
            match req.on_conflict {
                OnConflict::Duplicate => {
                    let deduped = dedup_dest_path(
                        state,
                        dst_ws,
                        dst_proj,
                        &p.path_str,
                        &req.from_workspace,
                        &used_dest_paths,
                    )
                    .await;
                    conflicts.push(PathConflict {
                        path: p.path_str.clone(),
                        moved_to: deduped.as_str().to_string(),
                    });
                    deduped
                }
                OnConflict::Overwrite => {
                    conflicts.push(PathConflict {
                        path: p.path_str.clone(),
                        moved_to: p.path_str.clone(),
                    });
                    p.path.clone()
                }
                OnConflict::Block => p.path.clone(), // unreachable
            }
        } else if used_dest_paths.contains(p.path_str.as_str()) {
            // The natural path is already claimed by an earlier
            // de-duplicated page; pick another to avoid clobbering it.
            let deduped = dedup_dest_path(
                state,
                dst_ws,
                dst_proj,
                &p.path_str,
                &req.from_workspace,
                &used_dest_paths,
            )
            .await;
            conflicts.push(PathConflict {
                path: p.path_str.clone(),
                moved_to: deduped.as_str().to_string(),
            });
            deduped
        } else {
            p.path.clone()
        };
        used_dest_paths.insert(dest_path.as_str().to_string());
        let new_page_id = match copy_wiki
            .write_page(WritePageRequest {
                workspace_id: dst_ws,
                project_id: dst_proj,
                path: dest_path.clone(),
                frontmatter: md.frontmatter,
                body: md.body,
                tier: p.tier,
                pinned: p.pinned,
                // Preserve the stored title verbatim (PageSummary.title is
                // the DB-derived title), rather than re-deriving it.
                title: Some(p.title.clone()),
                // Skip the named contributors enrich webhook on move copies:
                // the frontmatter (including the contributors list) is copied
                // verbatim, so re-enriching each copy adds nothing but blocking
                // per-page latency to a bulk move. write_page still resolves
                // the destination NAMES and runs the other hooks (git-mirror),
                // so the copy lands under the destination path.
                admission_ctx: Some(AdmissionContext {
                    skip_webhooks: vec![CONTRIBUTORS_WEBHOOK_NAME.to_string()],
                    ..AdmissionContext::default()
                }),
                author_id: None,
                actor: actor.clone(),
                evidence: Vec::new(),
            })
            .await
        {
            Ok(pid) => pid,
            // ANY copy failure aborts BEFORE the purge — the source survives.
            Err(e) => return Err(internal_err(format!("copy of {} failed: {e}", p.path_str))),
        };
        // Carry the source embedding over (skip the re-embed) when the source
        // had one for the current model.
        if let (Some((provider, model, dim)), Some(bytes)) =
            (&embed_meta, src_embeddings.get(&p.path_str))
            && let Err(e) = state
                .writer
                .store_embedding(
                    new_page_id,
                    bytes.clone(),
                    provider.clone(),
                    model.clone(),
                    *dim,
                )
                .await
        {
            warn!(path = %p.path_str, error = %e, "move-project: failed to carry embedding; page copied without it");
        }
        pages_copied += 1;
    }

    // Safety: a skipped (unreadable) source page blocks the purge — purging
    // now would destroy data we failed to copy. Report and let the operator
    // fix + re-run (re-running is idempotent: copied pages just supersede).
    if !pages_skipped.is_empty() {
        let checkpoint = checkpoint_or_warn(
            &state.wiki,
            format!(
                "move-project-partial {}/{} -> {}/{}",
                req.from_workspace, project_name, req.to_workspace, project_name
            ),
        );
        let report = MoveProjectReport {
            from: format!("{}/{}", req.from_workspace, project_name),
            to: format!("{}/{}", req.to_workspace, project_name),
            // copy_purge_merge is only reached from the merge branch
            // of handle_move_project; the destination project pre-existed.
            merged_into_existing: true,
            moved_via: "copy-purge",
            pages_copied,
            workstreams_moved: 0,
            pages_skipped,
            source_purged: false,
            source_pages_deleted: 0,
            source_sessions_deleted: 0,
            source_observations_deleted: 0,
            source_handoffs_deleted: 0,
            source_embeddings_deleted: 0,
            files_deleted: Vec::new(),
            files_failed: Vec::new(),
            conflicts,
            pre_checkpoint,
            checkpoint,
            manifest_warning: manifest_warning.clone(),
        };
        return Ok(report);
    }

    // PURGE the source — only reached when every page copied successfully.
    // Admission must run BEFORE the DB destruction so a `failure_policy =
    // reject` webhook can still abort the second leg of the move while the
    // source is intact (mirrors `handle_purge_project`'s ordering). The
    // previous version called `Wiki::purge_project` AFTER `writer.purge_project`,
    // which ran admit AFTER the rows were gone — reject came too late.
    let label = format!("{}/{}", req.from_workspace, project_name);
    let purge_ctx = AdmissionContext {
        workspace: req.from_workspace.clone(),
        project: project_name.to_string(),
        op: AdmissionOp::PurgeProject,
        actor,
        ..Default::default()
    };
    let resolved_purge_ctx = match state
        .wiki
        .admit_purge_project(src_ws, src_proj, Some(purge_ctx))
        .await
    {
        Ok(ctx) => ctx,
        Err(e) => return Err(internal_err(e.to_string())),
    };

    // The source purge is an internal step of move-project (a distinct op that
    // records its own move report); it is not attributed as a standalone
    // `purge_project` here, so the audit author is left NULL.
    // `Skip`: compaction is an operator's explicit choice on a destructive
    // command, not a side effect of moving a project. A `VACUUM` here would
    // rewrite the whole database in the middle of a move the caller asked to
    // be cheap.
    let summary = match state
        .writer
        .purge_project(
            src_ws,
            src_proj,
            &label,
            None,
            false,
            ai_memory_store::Compaction::Skip,
            ai_memory_store::PurgeMode::Commit,
        )
        .await
    {
        Ok(s) => s,
        // A live managed run under the source always blocks the destructive
        // second leg. `force` only overrides the active-project guard; unlike
        // a true move, copy-purge would delete the lease and strand the raw
        // transcript. The pages are already copied, so a later retry is
        // idempotent and leaves the source intact meanwhile.
        Err(e @ StoreError::ManagedRunActive { .. }) => {
            return Err((
                StatusCode::CONFLICT,
                Json(serde_json::json!({
                    "error": format!(
                        "{pages_copied} page(s) were copied to {}/{}, but the source \
                         {label} could not be purged: {e}. The source is intact. \
                         move-project --force cannot delete a live managed \
                         workstream during a copy-purge merge; finish or cancel \
                         the managed run, then retry.",
                        req.to_workspace, project_name,
                    )
                })),
            ));
        }
        Err(e) => return Err(internal_err(e.to_string())),
    };

    // Remove the source's wiki and raw-workstream directories, then dispatch
    // the non-blocking purge webhook. Pass the workspace/project names cached
    // in `resolved_purge_ctx`; the DB rows no longer exist for lookup.
    let (files_deleted, files_failed) = remove_purged_project_storage(
        state,
        src_ws,
        src_proj,
        &summary.workstream_ids,
        "move-project",
    )
    .await;
    // See `handle_purge_project` for the rationale on `partial_failure`.
    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(dispatch_ctx.as_ref());

    // The source project_id was just purged; if it was the published active
    // project, the pointer now dangles — clear it so the next hook re-resolves
    // to the (new) project rather than the deleted id.
    state.active_project.clear_project(src_proj);
    // Proactively drop any stale per-cwd cache entry for the purged source
    // project (its project_id no longer exists).
    invalidate_scope_cache(state, ScopeInvalidation::Project(src_proj)).await;

    if let Err(e) = state.wiki.backfill_scope_manifests().await {
        warn!(error = %e, "copy-purge move: scope-manifest backfill failed after move");
    }
    let checkpoint = checkpoint_or_warn(
        &state.wiki,
        format!(
            "move-project {}/{} -> {}/{}",
            req.from_workspace, project_name, req.to_workspace, project_name
        ),
    );

    let report = MoveProjectReport {
        from: label,
        to: format!("{}/{}", req.to_workspace, project_name),
        // copy_purge_merge is only reached from the merge branch.
        merged_into_existing: true,
        moved_via: "copy-purge",
        pages_copied,
        workstreams_moved: 0,
        pages_skipped: Vec::new(),
        source_purged: true,
        source_pages_deleted: summary.pages_deleted,
        source_sessions_deleted: summary.sessions_deleted,
        source_observations_deleted: summary.observations_deleted,
        source_handoffs_deleted: summary.handoffs_deleted,
        source_embeddings_deleted: summary.embeddings_deleted,
        files_deleted,
        files_failed,
        conflicts,
        pre_checkpoint,
        checkpoint,
        manifest_warning,
    };
    Ok(report)
}

// ---------------------------------------------------------------------
// merge-workspace
// ---------------------------------------------------------------------

/// JSON request body for `POST /admin/merge-workspace`.
#[derive(Deserialize)]
struct MergeWorkspaceRequest {
    /// Source workspace to drain and delete. Must exist; 404 on a typo.
    from: String,
    /// Destination workspace. Auto-created if absent (each per-project move
    /// get-or-creates it).
    to: String,
    /// Mandatory confirmation. The merge moves every source project (each a
    /// destructive move that purges the source project) and deletes the emptied
    /// source workspace, so without `confirm: true` the server returns 400.
    /// Defaulted so an omitted flag hits that explicit guard rather than a
    /// generic deserialization 422.
    #[serde(default)]
    confirm: bool,
    /// Override the live-session guard on every per-project move.
    #[serde(default)]
    force: bool,
    /// Conflict policy for a source project that already exists in the
    /// destination with colliding page paths (copy-purge merge). Default
    /// `block`. Projects with no destination twin are lossless true-moves and
    /// ignore this.
    #[serde(default)]
    on_conflict: OnConflict,
}

/// Wire-format report returned by `POST /admin/merge-workspace`.
#[derive(Debug, Serialize)]
pub struct MergeWorkspaceReport {
    /// Source workspace label.
    pub from: String,
    /// Destination workspace label.
    pub to: String,
    /// One move report per source project, in the order they were moved.
    pub projects_merged: Vec<MoveProjectReport>,
    /// Whether the now-empty source workspace was deleted at the end.
    pub source_workspace_deleted: bool,
}

/// `POST /admin/merge-workspace` — fold every project of `from` into `to`, then
/// delete the emptied `from`. Sugar over move-project: each source project runs
/// the same validated path, so a project that already exists in `to` merges by
/// content (copy-purge under `on_conflict`) while a fresh one is a lossless
/// re-stamp. Destructive (each move purges its source project and the source
/// workspace is removed), so `confirm=true` is required. Stops at the first
/// failing project — the moves already committed stand, and the failing project
/// plus the source workspace are left intact for the operator to resolve and
/// re-run (moves are idempotent).
async fn handle_merge_workspace(
    State(state): State<Arc<AdminState>>,
    actor_ext: Option<axum::Extension<ai_memory_core::ActorContext>>,
    Json(req): Json<MergeWorkspaceRequest>,
) -> impl IntoResponse {
    if !req.confirm {
        return (
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "error": "destructive operation requires confirm=true"
            })),
        );
    }
    if req.from == req.to {
        return (
            StatusCode::UNPROCESSABLE_ENTITY,
            Json(serde_json::json!({
                "error": "from and to are identical; nothing to merge"
            })),
        );
    }

    // Resolve the SOURCE without auto-creating — 404 on a typo, so a mistyped
    // source can't create then immediately delete a phantom workspace.
    if let Err(e) = lookup_ws_no_create(&state, &req.from).await {
        return e;
    }

    let projects = match state
        .reader
        .list_projects_with_stats_for_workspace(req.from.clone(), OPERATOR)
        .await
    {
        Ok(p) => p,
        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 mut merged: Vec<MoveProjectReport> = Vec::with_capacity(projects.len());
    for p in &projects {
        let move_req = MoveProjectRequest {
            from_workspace: req.from.clone(),
            project: Some(p.project_name.clone()),
            project_id: None,
            to_workspace: req.to.clone(),
            confirm: true,
            force: req.force,
            on_conflict: req.on_conflict,
            // `merge-workspace` is the explicit merge command: the operator
            // already asked for the two workspaces to be combined, so a
            // same-named project is merged rather than refused (#1713).
            allow_lossy_merge: true,
        };
        match move_project_core(&state, &move_req, actor.clone()).await {
            Ok(report) => merged.push(report),
            Err((status, body)) => {
                let reason = body
                    .0
                    .get("error")
                    .cloned()
                    .unwrap_or(serde_json::Value::Null);
                return (
                    status,
                    Json(serde_json::json!({
                        "error": format!(
                            "merge stopped at project '{}' in workspace '{}'",
                            p.project_name, req.from
                        ),
                        "failed_project": p.project_name,
                        "reason": reason,
                        "projects_merged": merged,
                        "source_workspace_deleted": false,
                    })),
                );
            }
        }
    }

    // Every project moved → the source workspace is now empty. Delete the shell
    // with force=false: it must be empty, so a race that repopulated it aborts
    // safely without wiping fresh data.
    let source_workspace_deleted = match delete_workspace_core(
        &state,
        &req.from,
        false,
        actor,
        // The shell is empty by this point; there is nothing to reclaim.
        ai_memory_store::Compaction::Skip,
    )
    .await
    {
        Ok(_) => true,
        Err((_status, body)) => {
            // The moves succeeded; only the final empty-shell delete failed
            // (e.g. a concurrent write recreated a project). No data was
            // lost, so report success-with-caveat instead of a hard error.
            warn!(
                workspace = %req.from,
                "merge-workspace: source drained but shell delete failed: {:?}",
                body
            );
            false
        }
    };

    let report = MergeWorkspaceReport {
        from: req.from,
        to: req.to,
        projects_merged: merged,
        source_workspace_deleted,
    };
    (
        StatusCode::OK,
        Json(serde_json::to_value(&report).unwrap_or(serde_json::Value::Null)),
    )
}

// ---------------------------------------------------------------------
// write-page
// ---------------------------------------------------------------------

/// JSON request body for `POST /admin/write-page`.
#[derive(Deserialize)]
struct WritePageAdminRequest {
    /// Workspace name (auto-created if absent).
    workspace: String,
    /// Project name (auto-created if absent).
    project: String,
    /// Relative wiki path (e.g. `concepts/foo.md`).
    path: String,
    /// Markdown body. The server frames it with frontmatter; pass plain body content.
    body: String,
    /// Optional title; derived from first H1 or path stem when absent.
    #[serde(default)]
    title: Option<String>,
    /// Semantic kind (`fact`, `rule`, `decision`, `gotcha`). Stored in
    /// the page frontmatter; the reader falls back to a path-derived
    /// kind when absent.
    #[serde(default)]
    kind: Option<String>,
    // The explicit legacy kind field consumes that key before flattening.
    #[serde(flatten)]
    metadata: ai_memory_core::page::PageWriteMetadata,
    /// Tier name (`working`, `episodic`, `semantic`, `procedural`).
    #[serde(default = "default_write_tier")]
    tier: String,
    /// Tags to attach to the page.
    #[serde(default)]
    tags: Vec<String>,
    /// Pin the page so the decay sweep skips it.
    #[serde(default)]
    pinned: bool,
}

fn default_write_tier() -> String {
    "semantic".to_string()
}

/// JSON response body for `POST /admin/write-page`.
#[derive(Serialize)]
struct WritePageResponse {
    /// UUID of the written page.
    page_id: String,
    /// Canonical wiki path.
    path: String,
    /// Post-write checkpoint, if the write changed the tree.
    #[serde(skip_serializing_if = "Option::is_none")]
    checkpoint: Option<String>,
    /// Non-fatal committed promotion manifest/checkpoint failure.
    #[serde(skip_serializing_if = "Option::is_none")]
    manifest_warning: Option<ai_memory_core::repository_identity::ManifestWarning>,
}

async fn handle_write_page(
    State(state): State<Arc<AdminState>>,
    actor_ext: Option<axum::Extension<ai_memory_core::ActorContext>>,
    author_ext: Option<axum::Extension<ai_memory_core::UserId>>,
    level_ext: Option<axum::Extension<ai_memory_core::AuthLevel>>,
    headers: HeaderMap,
    Json(req): Json<WritePageAdminRequest>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    let metadata = req.metadata.into_frontmatter().map_err(|e| {
        (
            StatusCode::UNPROCESSABLE_ENTITY,
            Json(serde_json::json!({ "error": e.to_string() })),
        )
    })?;
    let tier: Tier = req.tier.parse().map_err(|_| {
        (
            StatusCode::UNPROCESSABLE_ENTITY,
            Json(serde_json::json!({
                "error": format!("unknown tier '{}'", req.tier)
            })),
        )
    })?;

    let path = PagePath::new(req.path.clone()).map_err(|e| {
        (
            StatusCode::UNPROCESSABLE_ENTITY,
            Json(serde_json::json!({ "error": format!("invalid path: {e}") })),
        )
    })?;
    path.ensure_portable().map_err(|e| {
        (
            StatusCode::UNPROCESSABLE_ENTITY,
            Json(serde_json::json!({ "error": format!("invalid path: {e}") })),
        )
    })?;
    ai_memory_core::page::ensure_profile_metadata_placement(
        &metadata,
        &path,
        ai_memory_core::profile::is_reserved_scope_project(req.project.trim()),
    )
    .map_err(|e| {
        (
            StatusCode::UNPROCESSABLE_ENTITY,
            Json(serde_json::json!({ "error": e.to_string() })),
        )
    })?;

    let target = create_ws_proj(&state, &req.workspace, &req.project).await?;
    let (ws, proj) = target.scope.as_tuple();
    let manifest_warning = target.manifest_warning;

    let mut fm = metadata;
    if let Some(title) = &req.title {
        fm.insert("title".into(), serde_json::Value::String(title.clone()));
    }
    if let Some(kind) = req.kind.as_deref() {
        let kind = kind.trim();
        if !kind.is_empty() {
            fm.insert("kind".into(), serde_json::Value::String(kind.to_string()));
        }
    }
    if !req.tags.is_empty() {
        fm.insert(
            "tags".into(),
            serde_json::Value::Array(
                req.tags
                    .into_iter()
                    .map(serde_json::Value::String)
                    .collect(),
            ),
        );
    }
    if req.pinned {
        fm.insert("pinned".into(), serde_json::Value::Bool(true));
    }
    let frontmatter = if fm.is_empty() {
        serde_json::Value::Null
    } else {
        serde_json::Value::Object(fm)
    };

    let actor = actor_ext
        .map(|axum::Extension(actor)| actor)
        .unwrap_or_else(ai_memory_core::ActorContext::anonymous);
    let author_id = author_ext.map(|axum::Extension(author_id)| author_id);
    let skip_webhooks = skip_webhooks_for_admin_request(level_ext, &headers);
    let admission_ctx = if actor.has_any() || !skip_webhooks.is_empty() {
        Some(AdmissionContext {
            op: AdmissionOp::WritePage,
            skip_webhooks,
            ..AdmissionContext::default()
        })
    } else {
        None
    };

    let page_id = state
        .wiki
        .write_page(WritePageRequest {
            workspace_id: ws,
            project_id: proj,
            path: path.clone(),
            frontmatter,
            body: req.body,
            tier,
            pinned: req.pinned,
            title: req.title,
            admission_ctx,
            author_id,
            actor,
            evidence: Vec::new(),
        })
        .await
        .map_err(|e| {
            with_manifest_warning(internal_err(e.to_string()), manifest_warning.as_ref())
        })?;
    let checkpoint = checkpoint_or_warn(
        &state.wiki,
        format!(
            "write-page {}/{}: {}",
            req.workspace,
            req.project,
            path.as_str()
        ),
    );

    Ok((
        StatusCode::OK,
        Json(
            serde_json::to_value(WritePageResponse {
                page_id: page_id.to_string(),
                path: path.to_string(),
                checkpoint,
                manifest_warning,
            })
            .unwrap_or_else(|_| serde_json::json!({})),
        ),
    ))
}

// ---------------------------------------------------------------------
// delete-page
// ---------------------------------------------------------------------

/// JSON request body for `POST /admin/delete-page`.
///
/// Unlike `memory_delete_page` (MCP), this endpoint REQUIRES explicit
/// `workspace` so cross-workspace ambiguity can never silently route a
/// delete to the wrong slot.
#[derive(Deserialize)]
struct DeletePageAdminRequest {
    /// Workspace name. Required (no auto-create — delete acts on existing data).
    workspace: String,
    /// Project name within the workspace. Required.
    project: String,
    /// Relative wiki path (e.g. `concepts/foo.md`).
    path: String,
}

/// JSON response body for `POST /admin/delete-page`.
#[derive(Serialize)]
struct DeletePageResponse {
    /// Canonical wiki path of the deletion target.
    path: String,
    /// Always `true` on a successful (resolved-scope) call. `Wiki::delete_page`
    /// itself is idempotent — a missing file is treated as already-deleted —
    /// so the boolean reports "the call succeeded", not "a row was removed".
    /// The structural defense is in the 404 returned when `(workspace, project)`
    /// fails to resolve (so a stale or wrong-scope call never returns a misleading
    /// `deleted: true`).
    deleted: bool,
    /// Pre-delete checkpoint, if the tree had uncommitted changes.
    #[serde(skip_serializing_if = "Option::is_none")]
    pre_checkpoint: Option<String>,
    /// Post-delete checkpoint, if the delete changed the tree.
    #[serde(skip_serializing_if = "Option::is_none")]
    checkpoint: Option<String>,
}

async fn handle_delete_page(
    State(state): State<Arc<AdminState>>,
    actor_ext: Option<axum::Extension<ai_memory_core::ActorContext>>,
    level_ext: Option<axum::Extension<ai_memory_core::AuthLevel>>,
    author_ext: Option<axum::Extension<ai_memory_core::UserId>>,
    headers: HeaderMap,
    Json(req): Json<DeletePageAdminRequest>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    let path = PagePath::new(req.path.clone()).map_err(|e| {
        (
            StatusCode::UNPROCESSABLE_ENTITY,
            Json(serde_json::json!({ "error": format!("invalid path: {e}") })),
        )
    })?;

    // Use the no-create lookup (same as purge/rename/move): a delete on a
    // typo'd workspace/project must return 404, NOT silently auto-create
    // empty containers and then return `deleted: true` for nothing.
    let (ws, proj) = lookup_ws_proj_no_create(&state, &req.workspace, &req.project).await?;

    let pre_checkpoint = checkpoint_or_500(
        &state.wiki,
        format!(
            "pre-delete-page {}/{}: {}",
            req.workspace,
            req.project,
            path.as_str()
        ),
    )?;

    let actor = actor_ext
        .map(|axum::Extension(actor)| actor)
        .unwrap_or_else(ai_memory_core::ActorContext::anonymous);
    let skip_webhooks = skip_webhooks_for_admin_request(level_ext, &headers);
    let admission_ctx = if actor.has_any() || !skip_webhooks.is_empty() {
        Some(AdmissionContext {
            actor,
            op: AdmissionOp::Delete,
            skip_webhooks,
            ..AdmissionContext::default()
        })
    } else {
        None
    };

    let author_id = author_ext.map(|axum::Extension(u)| u);
    state
        .wiki
        .delete_page(ws, proj, &path, admission_ctx, author_id)
        .await
        .map_err(|e| internal_err(e.to_string()))?;
    let checkpoint = checkpoint_or_warn(
        &state.wiki,
        format!(
            "delete-page {}/{}: {}",
            req.workspace,
            req.project,
            path.as_str()
        ),
    );

    Ok((
        StatusCode::OK,
        Json(
            serde_json::to_value(DeletePageResponse {
                path: path.to_string(),
                deleted: true,
                pre_checkpoint,
                checkpoint,
            })
            .unwrap_or_else(|_| serde_json::json!({})),
        ),
    ))
}

// ---------------------------------------------------------------------
// user management (root-only)
// ---------------------------------------------------------------------

/// JSON request body for `POST /admin/users`.
#[derive(Debug, Deserialize)]
struct CreateUserRequest {
    username: String,
    #[serde(default)]
    name: Option<String>,
    #[serde(default)]
    email: Option<String>,
    #[serde(default)]
    role: Option<ai_memory_core::UserRole>,
}

#[derive(Debug, Deserialize)]
struct PatchUserRequest {
    #[serde(default)]
    name: Option<Option<String>>,
    #[serde(default)]
    email: Option<Option<String>>,
    #[serde(default)]
    role: Option<ai_memory_core::UserRole>,
}

#[derive(Debug, Deserialize)]
struct CreateApiCredentialRequest {
    username: String,
    label: String,
}

#[derive(Debug, Serialize)]
struct UserWithPasswordResponse {
    user: ai_memory_core::User,
    temporary_password: String,
}

#[derive(Debug, Serialize)]
struct UserResponse {
    user: ai_memory_core::User,
}

#[derive(Debug, Serialize)]
struct UserListResponse {
    users: Vec<ai_memory_core::User>,
}

#[derive(Debug, Serialize)]
struct ApiCredentialWithTokenResponse {
    credential: ai_memory_core::ApiCredential,
    token: String,
}

#[derive(Debug, Serialize)]
struct ApiCredentialListResponse {
    credentials: Vec<ai_memory_core::ApiCredential>,
}

fn require_root(
    level: ai_memory_core::AuthLevel,
) -> Result<(), (StatusCode, Json<serde_json::Value>)> {
    level
        .authorize(ai_memory_core::Capability::UserManagement, true)
        .map_err(|e| {
            let status = if e.is_authentication_required() {
                StatusCode::UNAUTHORIZED
            } else {
                StatusCode::FORBIDDEN
            };
            (status, Json(serde_json::json!({ "error": e.message() })))
        })
}

fn require_pepper(
    state: &AdminState,
) -> Result<&ai_memory_store::TokenPepper, (StatusCode, Json<serde_json::Value>)> {
    state.token_pepper.as_ref().ok_or_else(|| {
        (
            StatusCode::SERVICE_UNAVAILABLE,
            Json(serde_json::json!({
                "error": "multi-user not enabled (set [auth].token_pepper in config or run `ai-memory init`)"
            })),
        )
    })
}

fn reserved_password(
    auth: Option<axum::Extension<std::sync::Arc<crate::auth::AuthState>>>,
    password: &str,
) -> bool {
    auth.is_some_and(|axum::Extension(state)| {
        crate::human_auth::password_is_reserved(&state, password)
    })
}

async fn hash_temp_password() -> Result<String, (StatusCode, Json<serde_json::Value>)> {
    let raw = ai_memory_store::password::generate_temporary_password()
        .map_err(|e| internal_err(e.to_string()))?;
    ai_memory_core::validate_human_password(&raw, None, &[])
        .map_err(|e| validation_error(e.to_string()))?;
    Ok(raw)
}

async fn mint_temporary_password(
    state: &AdminState,
    auth: Option<axum::Extension<Arc<crate::auth::AuthState>>>,
) -> Result<String, (StatusCode, Json<serde_json::Value>)> {
    for _ in 0..8 {
        let raw = hash_temp_password().await?;
        if reserved_password(auth.clone(), &raw) {
            continue;
        }
        if let Some(pepper) = state.token_pepper.as_ref() {
            let hash = ai_memory_store::hash_token(&raw, pepper);
            match state.reader.token_hash_exists(hash).await {
                Ok(true) => continue,
                Ok(false) => {}
                Err(e) => return Err(internal_err(e.to_string())),
            }
        }
        return Ok(raw);
    }
    Err(internal_err(
        "could not mint a unique temporary password".to_string(),
    ))
}

async fn create_human_user_response(
    state: &AdminState,
    auth: Option<axum::Extension<Arc<crate::auth::AuthState>>>,
    req: CreateUserRequest,
) -> Result<(StatusCode, Json<serde_json::Value>), (StatusCode, Json<serde_json::Value>)> {
    let mut new_user = ai_memory_core::NewUser {
        username: req.username,
        name: req.name,
        email: req.email,
    };
    new_user
        .validate()
        .map_err(|e| validation_error(e.to_string()))?;
    let role = req.role.unwrap_or(ai_memory_core::UserRole::User);
    let raw = mint_temporary_password(state, auth).await?;
    let phc = ai_memory_store::password::hash_password(raw.clone())
        .await
        .map_err(|e| internal_err(e.to_string()))?;
    let user_id = state
        .writer
        .create_human_user(new_user, role, Some(phc), true)
        .await
        .map_err(map_user_store_err)?;
    let user = state
        .reader
        .find_user_by_id(user_id)
        .await
        .map_err(|e| internal_err(e.to_string()))?
        .ok_or_else(|| internal_err("created user vanished from store".to_string()))?;
    Ok((
        StatusCode::OK,
        Json(
            serde_json::to_value(UserWithPasswordResponse {
                user,
                temporary_password: raw,
            })
            .unwrap_or_default(),
        ),
    ))
}

async fn handle_create_human_user(
    State(state): State<Arc<AdminState>>,
    axum::Extension(level): axum::Extension<ai_memory_core::AuthLevel>,
    auth: Option<axum::Extension<Arc<crate::auth::AuthState>>>,
    Json(req): Json<CreateUserRequest>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    require_root(level)?;
    create_human_user_response(&state, auth, req).await
}

async fn handle_list_users(
    State(state): State<Arc<AdminState>>,
    axum::Extension(level): axum::Extension<ai_memory_core::AuthLevel>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    require_root(level)?;
    let users = state
        .reader
        .list_users()
        .await
        .map_err(|e| internal_err(e.to_string()))?;
    Ok((
        StatusCode::OK,
        Json(serde_json::to_value(UserListResponse { users }).unwrap_or_default()),
    ))
}

async fn handle_patch_user(
    State(state): State<Arc<AdminState>>,
    axum::Extension(level): axum::Extension<ai_memory_core::AuthLevel>,
    axum::extract::Path(username): axum::extract::Path<String>,
    Json(req): Json<PatchUserRequest>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    require_root(level)?;
    let user = lookup_user_by_username(&state, &username).await?;
    state
        .writer
        .patch_user(user.id, req.name, req.email, req.role)
        .await
        .map_err(map_user_store_err)?;
    let user = state
        .reader
        .find_user_by_id(user.id)
        .await
        .map_err(|e| internal_err(e.to_string()))?
        .ok_or_else(|| internal_err("user vanished after patch".to_string()))?;
    Ok((
        StatusCode::OK,
        Json(serde_json::to_value(UserResponse { user }).unwrap_or_default()),
    ))
}

async fn handle_reset_password(
    State(state): State<Arc<AdminState>>,
    axum::Extension(level): axum::Extension<ai_memory_core::AuthLevel>,
    auth: Option<axum::Extension<Arc<crate::auth::AuthState>>>,
    axum::extract::Path(username): axum::extract::Path<String>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    require_root(level)?;
    let user = lookup_user_by_username(&state, &username).await?;
    let raw = mint_temporary_password(&state, auth).await?;
    let phc = ai_memory_store::password::hash_password(raw.clone())
        .await
        .map_err(|e| internal_err(e.to_string()))?;
    state
        .writer
        .reset_human_password(user.id, phc, true)
        .await
        .map_err(map_user_store_err)?;
    let user = state
        .reader
        .find_user_by_id(user.id)
        .await
        .map_err(|e| internal_err(e.to_string()))?
        .ok_or_else(|| internal_err("user vanished after reset".to_string()))?;
    Ok((
        StatusCode::OK,
        Json(
            serde_json::to_value(UserWithPasswordResponse {
                user,
                temporary_password: raw,
            })
            .unwrap_or_default(),
        ),
    ))
}

async fn handle_disable_user(
    State(state): State<Arc<AdminState>>,
    axum::Extension(level): axum::Extension<ai_memory_core::AuthLevel>,
    axum::extract::Path(username): axum::extract::Path<String>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    require_root(level)?;
    let user = lookup_user_by_username(&state, &username).await?;
    state
        .writer
        .set_user_disabled(user.id, true)
        .await
        .map_err(map_user_store_err)?;
    let user = state
        .reader
        .find_user_by_id(user.id)
        .await
        .map_err(|e| internal_err(e.to_string()))?
        .ok_or_else(|| internal_err("user vanished after disable".to_string()))?;
    Ok((
        StatusCode::OK,
        Json(serde_json::to_value(UserResponse { user }).unwrap_or_default()),
    ))
}

async fn handle_enable_user(
    State(state): State<Arc<AdminState>>,
    axum::Extension(level): axum::Extension<ai_memory_core::AuthLevel>,
    axum::extract::Path(username): axum::extract::Path<String>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    require_root(level)?;
    let user = lookup_user_by_username(&state, &username).await?;
    state
        .writer
        .set_user_disabled(user.id, false)
        .await
        .map_err(map_user_store_err)?;
    let user = state
        .reader
        .find_user_by_id(user.id)
        .await
        .map_err(|e| internal_err(e.to_string()))?
        .ok_or_else(|| internal_err("user vanished after enable".to_string()))?;
    Ok((
        StatusCode::OK,
        Json(serde_json::to_value(UserResponse { user }).unwrap_or_default()),
    ))
}

async fn handle_create_api_credential(
    State(state): State<Arc<AdminState>>,
    axum::Extension(level): axum::Extension<ai_memory_core::AuthLevel>,
    Json(req): Json<CreateApiCredentialRequest>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    require_root(level)?;
    let pepper = require_pepper(&state)?;
    let user = lookup_user_by_username(&state, &req.username).await?;
    let token = ai_memory_store::generate_api_key().map_err(|e| internal_err(e.to_string()))?;
    let token_hash = ai_memory_store::hash_token(&token, pepper);
    let preview = ai_memory_store::api_key_preview(&token);
    let id = state
        .writer
        .create_api_credential(
            ai_memory_core::ApiCredentialId::new(),
            user.id,
            req.label,
            token_hash,
            Some(preview),
        )
        .await
        .map_err(map_user_store_err)?;
    let credential = state
        .reader
        .find_api_credential(id)
        .await
        .map_err(|e| internal_err(e.to_string()))?
        .ok_or_else(|| internal_err("credential vanished after create".to_string()))?;
    Ok((
        StatusCode::OK,
        Json(
            serde_json::to_value(ApiCredentialWithTokenResponse { credential, token })
                .unwrap_or_default(),
        ),
    ))
}

async fn handle_list_api_credentials(
    State(state): State<Arc<AdminState>>,
    axum::Extension(level): axum::Extension<ai_memory_core::AuthLevel>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    require_root(level)?;
    let credentials = state
        .reader
        .list_api_credentials()
        .await
        .map_err(|e| internal_err(e.to_string()))?;
    Ok((
        StatusCode::OK,
        Json(serde_json::to_value(ApiCredentialListResponse { credentials }).unwrap_or_default()),
    ))
}

async fn handle_rotate_api_credential(
    State(state): State<Arc<AdminState>>,
    axum::Extension(level): axum::Extension<ai_memory_core::AuthLevel>,
    axum::extract::Path(id): axum::extract::Path<String>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    require_root(level)?;
    let pepper = require_pepper(&state)?;
    let id: ai_memory_core::ApiCredentialId = id
        .parse()
        .map_err(|e: ai_memory_core::MemoryError| validation_error(e.to_string()))?;
    let token = ai_memory_store::generate_api_key().map_err(|e| internal_err(e.to_string()))?;
    let token_hash = ai_memory_store::hash_token(&token, pepper);
    let preview = ai_memory_store::api_key_preview(&token);
    let updated = state
        .writer
        .rotate_api_credential(id, token_hash, Some(preview))
        .await
        .map_err(map_user_store_err)?;
    if !updated {
        return Err((
            StatusCode::NOT_FOUND,
            Json(serde_json::json!({ "error": "no such credential" })),
        ));
    }
    let credential = state
        .reader
        .find_api_credential(id)
        .await
        .map_err(|e| internal_err(e.to_string()))?
        .ok_or_else(|| internal_err("credential vanished after rotate".to_string()))?;
    Ok((
        StatusCode::OK,
        Json(
            serde_json::to_value(ApiCredentialWithTokenResponse { credential, token })
                .unwrap_or_default(),
        ),
    ))
}

async fn handle_revoke_api_credential(
    State(state): State<Arc<AdminState>>,
    axum::Extension(level): axum::Extension<ai_memory_core::AuthLevel>,
    axum::extract::Path(id): axum::extract::Path<String>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    require_root(level)?;
    let id: ai_memory_core::ApiCredentialId = id
        .parse()
        .map_err(|e: ai_memory_core::MemoryError| validation_error(e.to_string()))?;
    state
        .writer
        .revoke_api_credential(id)
        .await
        .map_err(|e| internal_err(e.to_string()))?;
    let credential = state
        .reader
        .find_api_credential(id)
        .await
        .map_err(|e| internal_err(e.to_string()))?
        .ok_or_else(|| {
            (
                StatusCode::NOT_FOUND,
                Json(serde_json::json!({ "error": "no such credential" })),
            )
        })?;
    Ok((
        StatusCode::OK,
        Json(serde_json::json!({ "credential": credential })),
    ))
}

/// Body of `POST /admin/users/{username}/grant` and `…/revoke` (#708).
///
/// Names, not ids: this is what an operator types. `level` is required by
/// grant — never defaulted — and ignored by revoke, which takes away whatever
/// is held.
#[derive(Debug, Deserialize)]
struct UserGrantRequest {
    workspace: String,
    project: String,
    #[serde(default)]
    level: Option<String>,
}

/// Resolve a grant's user and project to the ids the table keys on.
///
/// The project is looked up, never created: granting access to a project that
/// does not exist yet would be a typo that silently succeeds and then grants
/// nothing anyone can reach.
async fn grant_target(
    state: &AdminState,
    username: &str,
    request: &UserGrantRequest,
) -> Result<(ai_memory_core::UserId, ProjectId), (StatusCode, Json<serde_json::Value>)> {
    let user = lookup_user_by_username(state, username.trim()).await?;
    let (_, project) =
        lookup_ws_proj_no_create(state, request.workspace.trim(), request.project.trim()).await?;
    Ok((user.id, project))
}

fn grants_json(grants: Vec<ai_memory_store::GrantListing>) -> Json<serde_json::Value> {
    let grants: Vec<_> = grants
        .into_iter()
        .map(|g| {
            serde_json::json!({
                "username": g.username,
                "workspace": g.workspace,
                "project": g.project,
                "level": g.level.as_str(),
            })
        })
        .collect();
    Json(serde_json::json!({ "grants": grants }))
}

/// `GET /admin/users/{username}/grants` — every project one user holds a
/// grant on.
async fn handle_list_user_grants(
    State(state): State<Arc<AdminState>>,
    axum::Extension(level): axum::Extension<ai_memory_core::AuthLevel>,
    axum::extract::Path(username): axum::extract::Path<String>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    require_root(level)?;
    let user = lookup_user_by_username(&state, username.trim()).await?;
    let grants = state
        .reader
        .list_grants(ai_memory_store::GrantFilter::User(user.id))
        .await
        .map_err(|e| internal_err(e.to_string()))?;
    Ok((StatusCode::OK, grants_json(grants)))
}

/// Query of `GET /admin/projects/grants`: both names for one project, or
/// neither for every grant on the server.
#[derive(Debug, Deserialize)]
struct ProjectGrantsQuery {
    workspace: Option<String>,
    project: Option<String>,
}

/// `GET /admin/projects/grants[?workspace=&project=]` — who holds a grant on
/// one project, or every grant on the server.
async fn handle_list_project_grants(
    State(state): State<Arc<AdminState>>,
    axum::Extension(level): axum::Extension<ai_memory_core::AuthLevel>,
    Query(query): Query<ProjectGrantsQuery>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    require_root(level)?;
    let filter = match (query.workspace.as_deref(), query.project.as_deref()) {
        (None, None) => ai_memory_store::GrantFilter::All,
        (Some(workspace), Some(project)) => {
            let (_, project) =
                lookup_ws_proj_no_create(&state, workspace.trim(), project.trim()).await?;
            ai_memory_store::GrantFilter::Project(project)
        }
        _ => {
            return Err(validation_error(
                "pass both workspace and project, or neither for every grant".into(),
            ));
        }
    };
    let grants = state
        .reader
        .list_grants(filter)
        .await
        .map_err(|e| internal_err(e.to_string()))?;
    Ok((StatusCode::OK, grants_json(grants)))
}

/// `POST /admin/users/{username}/grant` — give a user a level on a project, or
/// change the level they hold.
///
/// Returns what actually happened, so "already had that" is not reported as a
/// change.
async fn handle_user_grant(
    State(state): State<Arc<AdminState>>,
    axum::Extension(level): axum::Extension<ai_memory_core::AuthLevel>,
    operator: Option<axum::Extension<ai_memory_core::UserId>>,
    axum::extract::Path(username): axum::extract::Path<String>,
    Json(request): Json<UserGrantRequest>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    require_root(level)?;
    // Refuse rather than default. A grant whose level was mistyped must not
    // quietly become `write`: the operator meant *something*, and guessing
    // which in an authorization table is how access gets wider than intended.
    let grant_level = request
        .level
        .as_deref()
        .ok_or_else(|| validation_error("level is required: read or write".into()))
        .and_then(|raw| {
            ai_memory_store::GrantLevel::from_db(raw.trim())
                .ok_or_else(|| validation_error(format!("unknown level {raw:?}: read or write")))
        })?;
    let (user, project) = grant_target(&state, &username, &request).await?;
    let outcome = state
        .writer
        .grant_memory(
            user,
            project,
            grant_level,
            operator.map(|axum::Extension(id)| id),
        )
        .await
        .map_err(|e| internal_err(e.to_string()))?;
    let (changed, previous) = match outcome {
        ai_memory_store::GrantOutcome::Granted => (true, None),
        ai_memory_store::GrantOutcome::LevelChanged { from } => (true, Some(from.as_str())),
        ai_memory_store::GrantOutcome::Unchanged => (false, Some(grant_level.as_str())),
    };
    Ok((
        StatusCode::OK,
        Json(serde_json::json!({
            "username": username.trim(),
            "workspace": request.workspace.trim(),
            "project": request.project.trim(),
            "level": grant_level.as_str(),
            "changed": changed,
            "previous": previous,
        })),
    ))
}

/// `POST /admin/users/{username}/revoke` — take away whatever a user holds on
/// a project.
async fn handle_user_revoke(
    State(state): State<Arc<AdminState>>,
    axum::Extension(level): axum::Extension<ai_memory_core::AuthLevel>,
    operator: Option<axum::Extension<ai_memory_core::UserId>>,
    axum::extract::Path(username): axum::extract::Path<String>,
    Json(request): Json<UserGrantRequest>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    require_root(level)?;
    let (user, project) = grant_target(&state, &username, &request).await?;
    let revoked = state
        .writer
        .revoke_memory(user, project, operator.map(|axum::Extension(id)| id))
        .await
        .map_err(|e| internal_err(e.to_string()))?;
    Ok((
        StatusCode::OK,
        Json(serde_json::json!({
            "username": username.trim(),
            "workspace": request.workspace.trim(),
            "project": request.project.trim(),
            "revoked": revoked,
        })),
    ))
}

/// Body of `POST /admin/projects/access`.
#[derive(Debug, serde::Deserialize)]
struct ProjectAccessRequest {
    workspace: String,
    project: String,
    mode: Option<String>,
}

/// `POST /admin/projects/access` — set a project `open` or `restricted` (#708).
///
/// Restricting admits only root and grant holders from the next request on —
/// the creator holds `write` from the moment they created it. The response
/// names the page authors who hold no grant and so lose access, so the
/// operator can grant the ones who should keep it. Nothing is granted
/// automatically: restricting is the action meant to narrow access, and it must
/// not widen it on the way.
async fn handle_project_access(
    State(state): State<Arc<AdminState>>,
    axum::Extension(level): axum::Extension<ai_memory_core::AuthLevel>,
    Json(request): Json<ProjectAccessRequest>,
) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {
    require_root(level)?;
    // Required, never defaulted: a mistyped mode must not quietly become one
    // the operator did not ask for.
    let mode = request
        .mode
        .as_deref()
        .map(str::trim)
        .and_then(|raw| match raw {
            "open" => Some(ai_memory_store::AccessMode::Open),
            "restricted" => Some(ai_memory_store::AccessMode::Restricted),
            _ => None,
        })
        .ok_or_else(|| validation_error("mode is required: open or restricted".into()))?;
    let (workspace, project) = (request.workspace.trim(), request.project.trim());
    if project == ai_memory_core::GLOBAL_SCOPE_PROJECT {
        return Err(validation_error(format!(
            "{project} is the shared preferences scope, read by every user; it cannot be restricted"
        )));
    }
    // A profile project's mode is fixed by its kind: a private profile stays
    // restricted to its owner, a workspace profile stays readable by the
    // workspace. Changing either would expose or hide a profile wholesale.
    if ai_memory_core::profile::is_profile_project(project) {
        return Err(validation_error(format!(
            "{project} is a cross-project profile; its access mode is fixed"
        )));
    }
    let (_, project_id) = lookup_ws_proj_no_create(&state, workspace, project).await?;
    let previous = state
        .writer
        .set_access_mode(project_id, mode)
        .await
        .map_err(|e| internal_err(e.to_string()))?
        .ok_or_else(|| {
            (
                StatusCode::NOT_FOUND,
                Json(serde_json::json!({ "error": format!("no project {workspace}/{project}") })),
            )
        })?;
    let without_access = if mode == ai_memory_store::AccessMode::Restricted {
        state
            .reader
            .authors_without_grant(project_id)
            .await
            .map_err(|e| internal_err(e.to_string()))?
    } else {
        Vec::new()
    };
    Ok((
        StatusCode::OK,
        Json(serde_json::json!({
            "workspace": workspace,
            "project": project,
            "mode": mode.as_str(),
            "previous": previous.as_str(),
            "changed": previous != mode,
            "without_access": without_access,
        })),
    ))
}

async fn lookup_user_by_username(
    state: &AdminState,
    username: &str,
) -> Result<ai_memory_core::User, (StatusCode, Json<serde_json::Value>)> {
    let found = state
        .reader
        .find_user_by_username(username.to_string())
        .await
        .map_err(|e| internal_err(e.to_string()))?;
    found.ok_or_else(|| {
        (
            StatusCode::NOT_FOUND,
            Json(serde_json::json!({ "error": format!("no such user: {username}") })),
        )
    })
}

fn validation_error(msg: String) -> (StatusCode, Json<serde_json::Value>) {
    (
        StatusCode::BAD_REQUEST,
        Json(serde_json::json!({ "error": msg })),
    )
}

fn map_user_store_err(e: ai_memory_store::StoreError) -> (StatusCode, Json<serde_json::Value>) {
    match e {
        ai_memory_store::StoreError::Duplicate(msg)
        | ai_memory_store::StoreError::InvalidState(msg) => (
            StatusCode::CONFLICT,
            Json(serde_json::json!({ "error": msg })),
        ),
        ai_memory_store::StoreError::Memory(ai_memory_core::MemoryError::InvalidUsername(msg))
        | ai_memory_store::StoreError::Memory(ai_memory_core::MemoryError::InvalidEmail(msg))
        | ai_memory_store::StoreError::Memory(ai_memory_core::MemoryError::InvalidPassword(msg)) => {
            validation_error(msg)
        }
        other => internal_err(other.to_string()),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use ai_memory_core::{
        ActorContext, AgentKind, IdentityKey, NewObservation, NewSession, ObservationKind,
    };
    use ai_memory_core::{Sanitized, Sanitizer};
    use ai_memory_llm::{ChatRequest, ChatResponse, LlmOperationId, LlmResult, LlmWorkload};
    use ai_memory_store::Store;
    use axum::body::to_bytes;
    use axum::http::Request;
    use tempfile::TempDir;
    use tower::ServiceExt;

    async fn message_send_fixture(
        reject: bool,
    ) -> (
        TempDir,
        Store,
        Router,
        WorkspaceId,
        ProjectId,
        tokio::sync::mpsc::Receiver<(serde_json::Value, usize)>,
        Arc<tokio::sync::Notify>,
        tokio::task::JoinHandle<()>,
    ) {
        use ai_memory_wiki::{AdmissionChain, FailurePolicy, WebhookConfig};
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        store
            .writer
            .get_or_create_project(ws, "sender", None)
            .await
            .unwrap();
        let recipient = store
            .writer
            .get_or_create_project(ws, "recipient", None)
            .await
            .unwrap();
        let reader = store.reader.clone();
        let (tx, rx) = tokio::sync::mpsc::channel(4);
        let release = Arc::new(tokio::sync::Notify::new());
        let wait = release.clone();
        let app = Router::new().route(
            "/observer",
            post(move |Json(body): Json<serde_json::Value>| {
                let reader = reader.clone();
                let tx = tx.clone();
                let wait = wait.clone();
                async move {
                    let messages = reader
                        .list_messages(ws, recipient, ai_memory_core::MessageBox::Inbox, 256)
                        .await
                        .unwrap();
                    tx.send((body, messages.len())).await.unwrap();
                    if reject {
                        StatusCode::FORBIDDEN
                    } else {
                        // A slow observer must not hold up the CLI send response.
                        wait.notified().await;
                        StatusCode::NO_CONTENT
                    }
                }
            }),
        );
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let url = format!("http://{}/observer", listener.local_addr().unwrap());
        let server = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
        let chain = AdmissionChain::new(vec![WebhookConfig {
            name: "mail-observer".into(),
            url,
            timeout_ms: 2_000,
            failure_policy: if reject {
                FailurePolicy::Reject
            } else {
                FailurePolicy::Ignore
            },
            events: vec![AdmissionOp::MessageSend],
            blocking: reject,
        }])
        .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone())
            .with_admission_chain(chain);
        let router = admin_router(admin_state_for_store(&tmp, &store, wiki));
        (tmp, store, router, ws, recipient, rx, release, server)
    }

    fn message_send_request() -> Request<Body> {
        Request::builder()
            .method("POST")
            .uri("/admin/messages/send")
            .header("content-type", "application/json")
            .extension(ActorContext {
                user: Some("alice".into()),
                ..Default::default()
            })
            .body(Body::from(
                serde_json::json!({
                    "from_workspace": "default", "from_project": "sender",
                    "to_workspace": "default", "to_project": "recipient",
                    "body": "Synthetic result"
                })
                .to_string(),
            ))
            .unwrap()
    }

    #[tokio::test]
    async fn admin_message_send_observer_sees_commit_without_blocking_response() {
        let (_tmp, _store, router, _ws, _recipient, mut rx, release, server) =
            message_send_fixture(false).await;
        let response = tokio::time::timeout(
            std::time::Duration::from_secs(1),
            router.oneshot(message_send_request()),
        )
        .await
        .unwrap()
        .unwrap();
        assert_eq!(response.status(), StatusCode::OK);
        let (payload, committed_count) =
            tokio::time::timeout(std::time::Duration::from_secs(1), rx.recv())
                .await
                .unwrap()
                .unwrap();
        assert_eq!(committed_count, 1, "observer must run after commit");
        assert_eq!(payload["ctx"]["op"], "message_send");
        assert_eq!(payload["ctx"]["workspace"], "default");
        assert_eq!(payload["ctx"]["project"], "recipient");
        assert_eq!(payload["ctx"]["actor"]["user"], "alice");
        assert_eq!(
            payload["page"]["body"], "",
            "observer must not copy message text"
        );
        release.notify_one();
        server.abort();
    }

    #[tokio::test]
    async fn admin_message_send_reject_leaves_inbox_empty() {
        let (_tmp, store, router, ws, recipient, mut rx, _release, server) =
            message_send_fixture(true).await;
        let response = router.oneshot(message_send_request()).await.unwrap();
        assert_eq!(response.status(), StatusCode::FORBIDDEN);
        let (_, committed_count) = rx.recv().await.unwrap();
        assert_eq!(committed_count, 0);
        assert!(
            store
                .reader
                .list_messages(ws, recipient, ai_memory_core::MessageBox::Inbox, 10)
                .await
                .unwrap()
                .is_empty()
        );
        server.abort();
    }

    #[tokio::test]
    async fn admin_message_send_full_inbox_does_not_notify_observer() {
        let (_tmp, store, router, ws, recipient, mut rx, _release, server) =
            message_send_fixture(false).await;
        let sender = store
            .writer
            .get_or_create_project(ws, "sender", None)
            .await
            .unwrap();
        for _ in 0..256 {
            store
                .writer
                .insert_message(ai_memory_core::NewAgentMessage {
                    from_workspace_id: ws,
                    from_project_id: sender,
                    from_agent: AgentKind::Other,
                    from_session_id: None,
                    from_owner_user: None,
                    to_workspace_id: ws,
                    to_project_id: recipient,
                    to_agent: None,
                    subject: None,
                    body: "fixture".into(),
                    nature: ai_memory_core::MessageNature::Unknown,
                    evidence: None,
                })
                .await
                .unwrap();
        }
        let response = router.oneshot(message_send_request()).await.unwrap();
        assert_eq!(response.status(), StatusCode::CONFLICT);
        assert!(
            tokio::time::timeout(std::time::Duration::from_millis(50), rx.recv())
                .await
                .is_err()
        );
        server.abort();
    }

    struct FakeAutoImproveLlm;

    #[async_trait::async_trait]
    impl LlmProvider for FakeAutoImproveLlm {
        fn name(&self) -> &'static str {
            "fake-auto-improve"
        }

        fn model(&self) -> &str {
            "fake-model"
        }

        async fn complete(&self, _request: ChatRequest) -> LlmResult<ChatResponse> {
            Ok(ChatResponse {
                text: String::new(),
                usage: None,
                model: self.model().to_string(),
            })
        }

        async fn complete_structured_raw(
            &self,
            _request: ChatRequest,
            _schema: serde_json::Value,
        ) -> LlmResult<serde_json::Value> {
            Ok(serde_json::json!({
                "summary": "two staged proposals",
                "proposals": [
                    {
                        "operation": "create_or_update",
                        "path": "_slots/current-focus.md",
                        "title": "Current Focus",
                        "kind": "slot",
                        "confidence": 0.95,
                        "rationale": "The current focus should be updated from the session.",
                        "evidence": [{"page":"session", "quote":"focus changed"}],
                        "body_markdown": "# Current Focus\n\nupdated focus proposal"
                    },
                    {
                        "operation": "create_or_update",
                        "path": "notes/new-auto-improve.md",
                        "title": "New Auto Improve Lesson",
                        "kind": "note",
                        "confidence": 0.93,
                        "rationale": "The session contains a durable lesson worth adding.",
                        "evidence": [{"page":"session", "quote":"durable lesson"}],
                        "body_markdown": "# New Auto Improve Lesson\n\nnew page proposal"
                    }
                ],
                "rejected_candidates": []
            }))
        }
    }

    #[tokio::test]
    async fn status_reports_provider_health_block() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let router = admin_router(AdminState {
            ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),
            mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),
            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: ProviderHealth::default(),
            decay_params: DecayParams::default(),
            contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
            contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
            data_dir: tmp.path().to_path_buf(),
            db_path: store.db_path().to_path_buf(),
            bind: "127.0.0.1:49374".to_string(),
            home_dir: None,
            bootstrap_lock: Arc::new(tokio::sync::Mutex::new(())),
            token_pepper: None,
            active_project: ai_memory_core::ActiveProject::new(),
            scope_invalidator: None,
            trusted_proxy_identity: false,
        });

        let resp = router
            .oneshot(
                Request::builder()
                    .uri("/admin/status")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(json["providers"]["llm"]["status"], "disabled");
        assert_eq!(json["providers"]["llm_workloads"], serde_json::json!([]));
        assert_eq!(json["providers"]["embedding"]["status"], "disabled");
        // 2.0 item 7: the report carries the wedged-writer gauge and the
        // wiki-format state — a fresh store is natively conformant (no
        // migration ran) with no backup archive.
        assert!(json["write_queue"].is_array(), "{json}");
        assert_eq!(json["wiki_format"]["okf_migrated"], false);
        assert!(json["wiki_format"]["backup_archive"].is_null());
    }

    #[tokio::test]
    async fn status_reports_bounded_content_free_llm_workload_telemetry() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let provider_health = ProviderHealth::default();
        let llm = provider_health.wrap_llm_provider(
            Arc::new(FakeAutoImproveLlm),
            "fake-auto-improve",
            "fake-model",
            None,
        );
        llm.complete_with_operation_id(
            ChatRequest::user_prompt("private prompt").with_max_tokens(16),
            LlmOperationId::for_workload(LlmWorkload::QueryAnswer),
        )
        .await
        .unwrap();
        let router = admin_router(AdminState {
            ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),
            mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),
            writer: store.writer.clone(),
            reader: store.reader.clone(),
            wiki,
            llm: Some(llm),
            auto_improve_require_approval: false,
            auto_improve_review_config: Default::default(),
            embedder: None,
            provider_health,
            decay_params: DecayParams::default(),
            contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
            contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
            data_dir: tmp.path().to_path_buf(),
            db_path: store.db_path().to_path_buf(),
            bind: "127.0.0.1:49374".to_string(),
            home_dir: None,
            bootstrap_lock: Arc::new(tokio::sync::Mutex::new(())),
            token_pepper: None,
            active_project: ai_memory_core::ActiveProject::new(),
            scope_invalidator: None,
            trusted_proxy_identity: false,
        });

        let resp = router
            .oneshot(
                Request::builder()
                    .uri("/admin/status")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        let workloads = json["providers"]["llm_workloads"].as_array().unwrap();
        assert_eq!(workloads.len(), LlmWorkload::ALL.len());
        let query_answer = workloads
            .iter()
            .find(|entry| entry["workload"] == "query-answer")
            .unwrap();
        assert_eq!(query_answer["calls"], 1);
        assert_eq!(query_answer["successes"], 1);
        assert_eq!(query_answer["errors"], 0);
        assert_eq!(query_answer["status"], "ok");
        assert_eq!(query_answer["usage_reported_calls"], 0);
        let encoded = serde_json::to_string(workloads).unwrap();
        assert!(!encoded.contains("private prompt"));
    }

    /// The MCP-only complement: per-client tool-call counters served
    /// back with the same window semantics as by-agent.
    #[tokio::test]
    async fn activity_by_client_aggregates_and_bounds_the_window() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let today = jiff::Timestamp::now()
            .as_microsecond()
            .div_euclid(US_PER_DAY);
        store
            .writer
            .bump_client_activity(vec![
                ("vscode".into(), today, 4, 1),
                ("vscode".into(), today - 40, 7, 0),
                ("claude-desktop".into(), today, 1, 0),
            ])
            .await
            .unwrap();

        let router = admin_router(AdminState {
            ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),
            mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),
            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: ProviderHealth::default(),
            decay_params: DecayParams::default(),
            contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
            contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
            data_dir: tmp.path().to_path_buf(),
            db_path: store.db_path().to_path_buf(),
            bind: "127.0.0.1:49376".to_string(),
            home_dir: None,
            bootstrap_lock: Arc::new(tokio::sync::Mutex::new(())),
            token_pepper: None,
            active_project: ai_memory_core::ActiveProject::new(),
            scope_invalidator: None,
            trusted_proxy_identity: false,
        });

        // Whole history: the 40-day-old bucket counts.
        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/admin/activity/by-client")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(
            json["by_client"],
            serde_json::json!([
                { "client": "vscode", "reads": 11, "writes": 1 },
                { "client": "claude-desktop", "reads": 1, "writes": 0 },
            ]),
            "volume-desc across all history: {json}"
        );

        // A 7-day window drops the old bucket.
        let resp = router
            .oneshot(
                Request::builder()
                    .uri("/admin/activity/by-client?since_days=7")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(
            json["by_client"][0],
            serde_json::json!({ "client": "vscode", "reads": 4, "writes": 1 }),
            "{json}"
        );
    }

    /// The dashboard read: session counts grouped per agent CLI, with the
    /// scope failing closed and never auto-created.
    #[tokio::test]
    async fn sessions_by_agent_counts_per_agent_and_fails_closed_on_unknown_scope() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let ws = store
            .writer
            .get_or_create_workspace("default".to_string())
            .await
            .unwrap();
        let target = store
            .writer
            .get_or_create_project(ws, "target".to_string(), None)
            .await
            .unwrap();
        let other_project = store
            .writer
            .get_or_create_project(ws, "other".to_string(), None)
            .await
            .unwrap();
        for (project_id, agent) in [
            (target, AgentKind::ClaudeCode),
            (target, AgentKind::ClaudeCode),
            (target, AgentKind::Cursor),
            // A different scope must not leak into the target's totals.
            (other_project, AgentKind::Codex),
        ] {
            store
                .writer
                .begin_session(NewSession {
                    occurred_at: None,
                    id: SessionId::new(),
                    workspace_id: ws,
                    project_id,
                    agent_kind: agent,
                    cwd: None,
                    actor_user: None,
                })
                .await
                .unwrap();
        }
        for (agent, owner) in [(AgentKind::ClaudeCode, "alice"), (AgentKind::Codex, "bob")] {
            store
                .writer
                .begin_session(NewSession {
                    occurred_at: None,
                    id: SessionId::new(),
                    workspace_id: ws,
                    project_id: target,
                    agent_kind: agent,
                    cwd: None,
                    actor_user: Some(IdentityKey::User(owner.into()).storage_key()),
                })
                .await
                .unwrap();
        }

        let router = admin_router(AdminState {
            ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),
            mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),
            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: ProviderHealth::default(),
            decay_params: DecayParams::default(),
            contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
            contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
            data_dir: tmp.path().to_path_buf(),
            db_path: store.db_path().to_path_buf(),
            bind: "127.0.0.1:49375".to_string(),
            home_dir: None,
            bootstrap_lock: Arc::new(tokio::sync::Mutex::new(())),
            token_pepper: None,
            active_project: ai_memory_core::ActiveProject::new(),
            scope_invalidator: None,
            trusted_proxy_identity: false,
        });

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/admin/sessions/by-agent?workspace=default&project=target")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(
            json["by_agent"],
            serde_json::json!([
                { "agent": "claude-code", "sessions": 2, "mixed_capture_sessions": 0 },
                { "agent": "cursor", "sessions": 1, "mixed_capture_sessions": 0 },
            ]),
            "counts are per agent, scoped, count-desc: {json}"
        );

        // A named operator sees their rows plus shared legacy rows, but not a
        // colleague's. The recovery switch deliberately includes all owners.
        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/admin/sessions/by-agent?workspace=default&project=target")
                    .extension(ActorContext {
                        user: Some("alice".into()),
                        ..ActorContext::default()
                    })
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(
            json["by_agent"],
            serde_json::json!([
                { "agent": "claude-code", "sessions": 3, "mixed_capture_sessions": 0 },
                { "agent": "cursor", "sessions": 1, "mixed_capture_sessions": 0 },
            ]),
            "named callers see own plus shared sessions only: {json}"
        );

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri(
                        "/admin/sessions/by-agent?workspace=default&project=target&all_owners=true",
                    )
                    .extension(ActorContext {
                        user: Some("alice".into()),
                        ..ActorContext::default()
                    })
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(
            json["by_agent"],
            serde_json::json!([
                { "agent": "claude-code", "sessions": 3, "mixed_capture_sessions": 0 },
                { "agent": "codex", "sessions": 1, "mixed_capture_sessions": 0 },
                { "agent": "cursor", "sessions": 1, "mixed_capture_sessions": 0 },
            ]),
            "all_owners includes every operator: {json}"
        );

        // Zero is the explicit all-history spelling and must not become an
        // empty time window.
        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/admin/sessions/by-agent?workspace=default&project=target&since_days=0")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(
            json["by_agent"].as_array().unwrap().len(),
            2,
            "since_days=0 means the whole history, not an empty window: {json}"
        );

        // A window wider than the epoch saturates into "all history" rather
        // than overflowing: `u32::MAX` days times a day of microseconds does
        // not fit in the i64 the cutoff is computed in.
        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri(
                        "/admin/sessions/by-agent\
                         ?workspace=default&project=target&since_days=4294967295",
                    )
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(
            json["by_agent"].as_array().unwrap().len(),
            2,
            "a saturating window counts everything, it does not panic or empty: {json}"
        );

        // Unknown scope fails closed with a 404 — never auto-created.
        let resp = router
            .oneshot(
                Request::builder()
                    .uri("/admin/sessions/by-agent?workspace=default&project=ghost")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::NOT_FOUND);
        assert!(
            store
                .reader
                .find_project(ws, "ghost".to_string())
                .await
                .unwrap()
                .is_none(),
            "read route must not auto-create scopes"
        );
    }

    #[tokio::test]
    async fn open_sessions_filters_by_scope_and_agent() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let ws = store
            .writer
            .get_or_create_workspace("default".to_string())
            .await
            .unwrap();
        let target = store
            .writer
            .get_or_create_project(ws, "target".to_string(), None)
            .await
            .unwrap();
        let other_project = store
            .writer
            .get_or_create_project(ws, "other".to_string(), None)
            .await
            .unwrap();
        let older = SessionId::new();
        let latest = SessionId::new();
        let other_agent = SessionId::new();
        let other_scope = SessionId::new();
        let ended = SessionId::new();
        let alice = SessionId::new();
        let bob = SessionId::new();
        for (id, project_id, agent) in [
            (older, target, AgentKind::Codex),
            (other_agent, target, AgentKind::ClaudeCode),
            (other_scope, other_project, AgentKind::Codex),
            (ended, target, AgentKind::Codex),
            (latest, target, AgentKind::Codex),
        ] {
            store
                .writer
                .begin_session(NewSession {
                    occurred_at: None,
                    id,
                    workspace_id: ws,
                    project_id,
                    agent_kind: agent,
                    cwd: Some(std::path::PathBuf::from("/tmp/target")),
                    actor_user: None,
                })
                .await
                .unwrap();
        }
        store.writer.end_session(ended, None).await.unwrap();
        for (id, user) in [(alice, "alice"), (bob, "bob")] {
            store
                .writer
                .begin_session(NewSession {
                    occurred_at: None,
                    id,
                    workspace_id: ws,
                    project_id: target,
                    agent_kind: AgentKind::Codex,
                    cwd: Some(std::path::PathBuf::from("/tmp/target")),
                    actor_user: Some(IdentityKey::User(user.into()).storage_key()),
                })
                .await
                .unwrap();
        }

        let router = admin_router(AdminState {
            ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),
            mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),
            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: ProviderHealth::default(),
            decay_params: DecayParams::default(),
            contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
            contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
            data_dir: tmp.path().to_path_buf(),
            db_path: store.db_path().to_path_buf(),
            bind: "127.0.0.1:49374".to_string(),
            home_dir: None,
            bootstrap_lock: Arc::new(tokio::sync::Mutex::new(())),
            token_pepper: None,
            active_project: ai_memory_core::ActiveProject::new(),
            scope_invalidator: None,
            trusted_proxy_identity: false,
        });

        // Default: only the newest open session for the scope + agent.
        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/admin/open-sessions?workspace=default&project=target&agent=codex")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        let sessions = json["sessions"].as_array().unwrap();
        assert_eq!(sessions.len(), 1);
        assert_eq!(sessions[0]["session_id"], latest.to_string());
        assert_eq!(sessions[0]["cwd"], "/tmp/target");

        // `all=true`: every open codex session in the scope, ended and
        // other-scope/other-agent sessions excluded.
        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/admin/open-sessions?workspace=default&project=target&agent=codex&all=true")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        let sessions = json["sessions"].as_array().unwrap();
        assert_eq!(sessions.len(), 2);
        let ids: Vec<&str> = sessions
            .iter()
            .map(|s| s["session_id"].as_str().unwrap())
            .collect();
        assert!(ids.contains(&latest.to_string().as_str()));
        assert!(ids.contains(&older.to_string().as_str()));

        // A named operator gets their own open sessions plus shared legacy
        // sessions, never a colleague's. This is the exact route consumed by
        // the destructive `finalize-session` command.
        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/admin/open-sessions?workspace=default&project=target&agent=codex&all=true")
                    .extension(ActorContext {
                        user: Some("alice".into()),
                        ..ActorContext::default()
                    })
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        let ids = json["sessions"]
            .as_array()
            .unwrap()
            .iter()
            .map(|session| session["session_id"].as_str().unwrap())
            .collect::<Vec<_>>();
        assert!(ids.contains(&alice.to_string().as_str()));
        assert!(ids.contains(&latest.to_string().as_str()));
        assert!(ids.contains(&older.to_string().as_str()));
        assert!(!ids.contains(&bob.to_string().as_str()));

        // Unknown agent kind fails closed with a 400.
        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/admin/open-sessions?workspace=default&project=target&agent=nope")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::BAD_REQUEST);

        // Unknown scope fails closed with a 404 — never auto-created.
        let resp = router
            .oneshot(
                Request::builder()
                    .uri("/admin/open-sessions?workspace=default&project=ghost&agent=codex")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::NOT_FOUND);
        assert!(
            store
                .reader
                .find_project(ws, "ghost".to_string())
                .await
                .unwrap()
                .is_none(),
            "read route must not auto-create scopes"
        );
    }

    /// Regression for the race a naive wrapper hits with several concurrent
    /// Kiro CLI tabs against one repo: two open sessions for the same
    /// agent+scope exist (`older`, `latest`), and `?session_id=` must return
    /// exactly the one requested — never falling back to "newest open" —
    /// while still composing with the owner filter (a session_id belonging
    /// to another operator must not be reachable just by knowing its id,
    /// same invariant `all_owners` already protects for the default query).
    #[tokio::test]
    async fn open_sessions_session_id_targets_exact_session() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let ws = store
            .writer
            .get_or_create_workspace("default".to_string())
            .await
            .unwrap();
        let target = store
            .writer
            .get_or_create_project(ws, "target".to_string(), None)
            .await
            .unwrap();
        let other_project = store
            .writer
            .get_or_create_project(ws, "other".to_string(), None)
            .await
            .unwrap();
        let older = SessionId::new();
        let latest = SessionId::new();
        let other_scope = SessionId::new();
        let ended = SessionId::new();
        let bobs_session = SessionId::new();
        let wrong_agent = SessionId::new();
        for (id, project_id, agent_kind, actor_user) in [
            (older, target, AgentKind::KiroCli, None),
            (latest, target, AgentKind::KiroCli, None),
            (other_scope, other_project, AgentKind::KiroCli, None),
            (ended, target, AgentKind::KiroCli, None),
            (wrong_agent, target, AgentKind::Codex, None),
            (
                bobs_session,
                target,
                AgentKind::KiroCli,
                Some(IdentityKey::User("bob".into()).storage_key()),
            ),
        ] {
            store
                .writer
                .begin_session(NewSession {
                    occurred_at: None,
                    id,
                    workspace_id: ws,
                    project_id,
                    agent_kind,
                    cwd: Some(std::path::PathBuf::from("/tmp/target")),
                    actor_user,
                })
                .await
                .unwrap();
        }
        store.writer.end_session(ended, None).await.unwrap();

        let router = admin_router(AdminState {
            ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),
            mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),
            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: ProviderHealth::default(),
            decay_params: DecayParams::default(),
            contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
            contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
            data_dir: tmp.path().to_path_buf(),
            db_path: store.db_path().to_path_buf(),
            bind: "127.0.0.1:49374".to_string(),
            home_dir: None,
            bootstrap_lock: Arc::new(tokio::sync::Mutex::new(())),
            token_pepper: None,
            active_project: ai_memory_core::ActiveProject::new(),
            scope_invalidator: None,
            trusted_proxy_identity: false,
        });

        // Targeting `older` by id must return only `older`, not `latest`.
        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri(format!(
                        "/admin/open-sessions?workspace=default&project=target&agent=kiro-cli&session_id={older}"
                    ))
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        let sessions = json["sessions"].as_array().unwrap();
        assert_eq!(sessions.len(), 1, "must not fall back to newest-open");
        assert_eq!(sessions[0]["session_id"], older.to_string());

        // A session id that belongs to a different project must not be
        // reachable just by knowing the id — scope is still enforced.
        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri(format!(
                        "/admin/open-sessions?workspace=default&project=target&agent=kiro-cli&session_id={other_scope}"
                    ))
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(
            json["sessions"].as_array().unwrap().len(),
            0,
            "a session from another project must not be reachable by id"
        );

        // An already-ended session id is not "open" and must not match.
        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri(format!(
                        "/admin/open-sessions?workspace=default&project=target&agent=kiro-cli&session_id={ended}"
                    ))
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(json["sessions"].as_array().unwrap().len(), 0);

        // The same ended session id IS reachable with `include_ended=true`
        // (the `finalize-session --reopen` path): the id still narrows the
        // response to exactly that session.
        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri(format!(
                        "/admin/open-sessions?workspace=default&project=target&agent=kiro-cli&session_id={ended}&include_ended=true"
                    ))
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        let sessions = json["sessions"].as_array().unwrap();
        assert_eq!(sessions.len(), 1);
        assert_eq!(sessions[0]["session_id"], ended.to_string());

        // `include_ended=true` without an exact id is rejected: reopening
        // must never become a bulk operation over every ended session.
        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri(
                        "/admin/open-sessions?workspace=default&project=target&agent=kiro-cli&include_ended=true",
                    )
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::BAD_REQUEST);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(json["error"], "include_ended requires session_id");

        // An exact id from another agent remains outside the requested
        // agent boundary even when its scope matches.
        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri(format!(
                        "/admin/open-sessions?workspace=default&project=target&agent=kiro-cli&session_id={wrong_agent}"
                    ))
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(json["sessions"].as_array().unwrap().len(), 0);

        // A colleague's session id is not reachable without all_owners, even
        // when the exact id is known — session_id composes with the owner
        // filter (AND), it doesn't bypass it.
        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri(format!(
                        "/admin/open-sessions?workspace=default&project=target&agent=kiro-cli&session_id={bobs_session}"
                    ))
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(
            json["sessions"].as_array().unwrap().len(),
            0,
            "session_id must not bypass the owner filter"
        );

        // ...but composes correctly WITH all_owners set.
        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri(format!(
                        "/admin/open-sessions?workspace=default&project=target&agent=kiro-cli&session_id={bobs_session}&all_owners=true"
                    ))
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(json["sessions"].as_array().unwrap().len(), 1);

        // Selection modes are mutually exclusive instead of silently giving
        // one of them precedence.
        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri(format!(
                        "/admin/open-sessions?workspace=default&project=target&agent=kiro-cli&all=true&session_id={older}"
                    ))
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::BAD_REQUEST);

        // A malformed session_id fails closed with a 400, not a silent
        // empty/ignored filter.
        let resp = router
            .oneshot(
                Request::builder()
                    .uri("/admin/open-sessions?workspace=default&project=target&agent=kiro-cli&session_id=not-a-uuid")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::BAD_REQUEST);
    }

    fn read_page_test_router() -> (TempDir, Router) {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let web = ai_memory_web::router(store.reader.clone(), wiki.clone());
        let router = admin_router(AdminState {
            ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),
            mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),
            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: ProviderHealth::default(),
            decay_params: DecayParams::default(),
            contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
            contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
            data_dir: tmp.path().to_path_buf(),
            db_path: store.db_path().to_path_buf(),
            bind: "127.0.0.1:49374".to_string(),
            home_dir: None,
            bootstrap_lock: Arc::new(tokio::sync::Mutex::new(())),
            token_pepper: None,
            active_project: ai_memory_core::ActiveProject::new(),
            scope_invalidator: None,
            trusted_proxy_identity: false,
        });
        (tmp, router.nest("/web", web))
    }

    /// The exported tarball is a valid OKF v0.2 bundle: fresh index.md
    /// with okf_version, every concept file conformant (docs/okf.md).
    #[tokio::test]
    async fn export_okf_streams_a_conformant_bundle() {
        let (_tmp, router) = read_page_test_router();
        post_write_page(
            &router,
            "default",
            "scratch",
            "gotchas/build.md",
            "watch out",
        )
        .await;

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/export-okf?workspace=default&project=scratch")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
            .await
            .unwrap();

        let dec = flate2::read::GzDecoder::new(std::io::Cursor::new(bytes.to_vec()));
        let mut ar = tar::Archive::new(dec);
        let mut names = Vec::new();
        let mut index_body = String::new();
        let mut page_body = String::new();
        for entry in ar.entries().unwrap() {
            let mut entry = entry.unwrap();
            let name = entry.path().unwrap().display().to_string();
            use std::io::Read as _;
            let mut content = String::new();
            entry.read_to_string(&mut content).unwrap();
            if name == "index.md" {
                index_body = content.clone();
            }
            if name == "gotchas/build.md" {
                page_body = content.clone();
            }
            names.push(name);
        }
        assert!(names.contains(&"index.md".to_string()), "{names:?}");
        assert!(names.contains(&"gotchas/build.md".to_string()), "{names:?}");
        assert!(index_body.contains("okf_version: \"0.2\""));
        let fm = ai_memory_wiki::parse(&page_body).unwrap().frontmatter;
        assert!(ai_memory_core::okf::is_conformant(&fm));
        assert_eq!(fm["type"], "Gotcha");
    }

    #[tokio::test]
    async fn export_okf_directory_index_links_are_clickable() {
        let (_tmp, router) = read_page_test_router();
        let cases = [
            ("notes", "notes", "notes/"),
            ("team notes", "team%20notes", "team notes/"),
            ("notes [draft", "notes%20%5Bdraft", "notes [draft/"),
            ("c# 50%", "c%23%2050%25", "c# 50%/"),
            ("日本語", "%E6%97%A5%E6%9C%AC%E8%AA%9E", "日本語/"),
            ("&copy;", "%26copy%3B", "&amp;copy;/"),
            ("`draft`", "%60draft%60", "`draft`/"),
            ("_draft_", "_draft_", "_draft_/"),
        ];
        for (family, _, _) in cases {
            post_write_page(
                &router,
                "default",
                "scratch",
                &format!("{family}/seed.md"),
                "# Seed",
            )
            .await;
        }
        let response = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/export-okf?workspace=default&project=scratch")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(response.status(), StatusCode::OK);
        let bytes = axum::body::to_bytes(response.into_body(), usize::MAX)
            .await
            .unwrap();
        let mut archive =
            tar::Archive::new(flate2::read::GzDecoder::new(std::io::Cursor::new(bytes)));
        let mut index = String::new();
        for entry in archive.entries().unwrap() {
            let mut entry = entry.unwrap();
            if entry.path().unwrap().as_ref() == std::path::Path::new("index.md") {
                use std::io::Read as _;
                entry.read_to_string(&mut index).unwrap();
            }
        }
        assert!(
            index.contains("- [notes/](notes/)\n"),
            "ordinary listing changed: {index}"
        );
        let body = ai_memory_wiki::parse(&index).unwrap().body;
        post_write_page(&router, "default", "scratch", "export-index.md", &body).await;
        let response = router
            .oneshot(
                Request::builder()
                    .uri("/web/w/default/scratch/p/export-index.md")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(response.status(), StatusCode::OK);
        let html = String::from_utf8(
            axum::body::to_bytes(response.into_body(), usize::MAX)
                .await
                .unwrap()
                .to_vec(),
        )
        .unwrap();
        for (family, encoded, label) in cases {
            assert!(
                html.contains(&format!(
                    "<a href=\"w/default/scratch/p/{encoded}\">{label}</a>"
                )),
                "rendered directory link missing or changed: {family}: {html}"
            );
        }
    }

    /// Issue #960 item 1: strict OKF validators read §11.3 ("follows the
    /// structure in §8") as rejecting prose outside the list structure. The
    /// generated `index.md` body, once its heading line is stripped, must
    /// consist only of blank lines and `- [...]` list entries.
    #[tokio::test]
    async fn export_okf_index_has_no_prose_outside_the_list() {
        let (_tmp, router) = read_page_test_router();
        post_write_page(
            &router,
            "default",
            "scratch",
            "gotchas/build.md",
            "watch out",
        )
        .await;

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/export-okf?workspace=default&project=scratch")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
            .await
            .unwrap();
        let dec = flate2::read::GzDecoder::new(std::io::Cursor::new(bytes.to_vec()));
        let mut ar = tar::Archive::new(dec);
        let mut index_body = String::new();
        for entry in ar.entries().unwrap() {
            let mut entry = entry.unwrap();
            if entry.path().unwrap().display().to_string() == "index.md" {
                use std::io::Read as _;
                entry.read_to_string(&mut index_body).unwrap();
            }
        }
        let parsed = ai_memory_wiki::parse(&index_body).unwrap();
        for line in parsed.body.lines() {
            let trimmed = line.trim();
            assert!(
                trimmed.is_empty() || trimmed.starts_with('#') || trimmed.starts_with("- "),
                "prose line outside the list structure: {line:?}\nfull body: {}",
                parsed.body
            );
        }
    }

    /// Issue #960 item 2: `derive_title` already knows the title (H1 or
    /// path stem), but until now nothing wrote it into exported frontmatter.
    /// Export-only: `title`/`description` land in the bundle's copy, never
    /// on the on-disk wiki file.
    #[tokio::test]
    async fn export_okf_backfills_title_and_description() {
        let (tmp, router) = read_page_test_router();
        post_write_page(&router, "default", "scratch", "notes/seed.md", "seed").await;
        let proj_dir = scratch_project_dir(tmp.path());
        std::fs::create_dir_all(proj_dir.join("concepts")).unwrap();

        // No title, no description/summary/abstract at all: title derives
        // from the H1 heading; no description key is invented.
        std::fs::write(
            proj_dir.join("concepts/no-title.md"),
            "---\ntype: Concept\n---\n\n# Heading Title\n\nBody.\n",
        )
        .unwrap();
        // `summary` present: description comes from it.
        std::fs::write(
            proj_dir.join("concepts/has-summary.md"),
            "---\ntype: Concept\nsummary: from summary\n---\n\nBody.\n",
        )
        .unwrap();
        // `abstract` but no `summary`: description falls back to it.
        std::fs::write(
            proj_dir.join("concepts/has-abstract.md"),
            "---\ntype: Concept\nabstract: from abstract\n---\n\nBody.\n",
        )
        .unwrap();
        // Explicit title/description already present: untouched.
        std::fs::write(
            proj_dir.join("concepts/explicit.md"),
            "---\ntype: Concept\ntitle: Explicit Title\ndescription: Explicit description\nsummary: ignored\n---\n\nBody.\n",
        )
        .unwrap();

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/export-okf?workspace=default&project=scratch")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
            .await
            .unwrap();
        let dec = flate2::read::GzDecoder::new(std::io::Cursor::new(bytes.to_vec()));
        let mut ar = tar::Archive::new(dec);
        let mut bodies = std::collections::HashMap::new();
        for entry in ar.entries().unwrap() {
            let mut entry = entry.unwrap();
            let name = entry.path().unwrap().display().to_string();
            use std::io::Read as _;
            let mut content = String::new();
            entry.read_to_string(&mut content).unwrap();
            bodies.insert(name, content);
        }

        let no_title = ai_memory_wiki::parse(&bodies["concepts/no-title.md"])
            .unwrap()
            .frontmatter;
        assert_eq!(no_title["title"], "Heading Title");
        assert!(no_title.get("description").is_none(), "{no_title:?}");

        let has_summary = ai_memory_wiki::parse(&bodies["concepts/has-summary.md"])
            .unwrap()
            .frontmatter;
        assert_eq!(has_summary["description"], "from summary");

        let has_abstract = ai_memory_wiki::parse(&bodies["concepts/has-abstract.md"])
            .unwrap()
            .frontmatter;
        assert_eq!(has_abstract["description"], "from abstract");

        let explicit = ai_memory_wiki::parse(&bodies["concepts/explicit.md"])
            .unwrap()
            .frontmatter;
        assert_eq!(explicit["title"], "Explicit Title");
        assert_eq!(explicit["description"], "Explicit description");

        // Never mutated on disk.
        let on_disk = std::fs::read_to_string(proj_dir.join("concepts/no-title.md")).unwrap();
        let on_disk_fm = ai_memory_wiki::parse(&on_disk).unwrap().frontmatter;
        assert!(on_disk_fm.get("title").is_none(), "{on_disk_fm:?}");
    }

    /// Issue #960 item 3: a generic OKF consumer has no idea what
    /// `[[decisions/b.md]]` means. Local wikilinks become bundle-relative
    /// Markdown links at export; a cross-project wikilink has no Markdown
    /// equivalent and ships untouched.
    #[tokio::test]
    async fn export_okf_rewrites_local_wikilinks_to_relative_markdown_links() {
        let (tmp, router) = read_page_test_router();
        post_write_page(&router, "default", "scratch", "notes/seed.md", "seed").await;
        let proj_dir = scratch_project_dir(tmp.path());
        std::fs::create_dir_all(proj_dir.join("concepts")).unwrap();
        std::fs::create_dir_all(proj_dir.join("decisions")).unwrap();
        std::fs::write(
            proj_dir.join("decisions/b.md"),
            "---\ntype: Decision\n---\n\nB.\n",
        )
        .unwrap();
        std::fs::write(
            proj_dir.join("concepts/a.md"),
            "---\ntype: Concept\n---\n\nSee [[decisions/b.md]] and [[other-project:x.md]].\n",
        )
        .unwrap();

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/export-okf?workspace=default&project=scratch")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
            .await
            .unwrap();
        let dec = flate2::read::GzDecoder::new(std::io::Cursor::new(bytes.to_vec()));
        let mut ar = tar::Archive::new(dec);
        let mut a_body = String::new();
        for entry in ar.entries().unwrap() {
            let mut entry = entry.unwrap();
            if entry.path().unwrap().display().to_string() == "concepts/a.md" {
                use std::io::Read as _;
                entry.read_to_string(&mut a_body).unwrap();
            }
        }
        let parsed = ai_memory_wiki::parse(&a_body).unwrap();
        assert!(
            parsed.body.contains("[decisions/b.md](../decisions/b.md)"),
            "{}",
            parsed.body
        );
        assert!(
            parsed.body.contains("[[other-project:x.md]]"),
            "cross-project wikilink must ship untouched: {}",
            parsed.body
        );

        // Never mutated on disk.
        let on_disk = std::fs::read_to_string(proj_dir.join("concepts/a.md")).unwrap();
        assert!(on_disk.contains("[[decisions/b.md]]"));
    }

    #[tokio::test]
    async fn export_okf_labels_preserve_links_when_the_bundle_is_reindexed() {
        let (tmp, router) = read_page_test_router();
        post_write_page(&router, "default", "scratch", "notes/seed.md", "seed").await;
        let project = scratch_project_dir(tmp.path());
        std::fs::create_dir_all(project.join("concepts")).unwrap();
        std::fs::write(
            project.join("concepts/a.md"),
            "---\ntype: Concept\n---\n\nSee [[notes/seed.md|array[0] access]].\n",
        )
        .unwrap();
        let response = router
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/export-okf?workspace=default&project=scratch")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(response.status(), StatusCode::OK);
        let bytes = axum::body::to_bytes(response.into_body(), usize::MAX)
            .await
            .unwrap();
        let decoder = flate2::read::GzDecoder::new(std::io::Cursor::new(bytes));
        let mut archive = tar::Archive::new(decoder);
        let mut exported = String::new();
        for entry in archive.entries().unwrap() {
            let mut entry = entry.unwrap();
            if entry.path().unwrap().display().to_string() == "concepts/a.md" {
                use std::io::Read as _;
                entry.read_to_string(&mut exported).unwrap();
            }
        }
        let document = ai_memory_wiki::parse(&exported).unwrap();
        let path = ai_memory_core::PagePath::new("concepts/a.md").unwrap();
        let links = ai_memory_wiki::extract_links(&document.body, &path);
        assert_eq!(links.len(), 1, "{exported}");
        assert_eq!(links[0].path.as_str(), "notes/seed.md");
    }

    /// Post-audit regression: the things a REAL deployment's tree holds
    /// beside concept pages — typed scope manifests and _pending
    /// proposal sidecars — must not block the export. Sidecars are
    /// excluded; manifests ship typed.
    #[tokio::test]
    async fn export_okf_tolerates_manifests_and_skips_pending() {
        let (tmp, router) = read_page_test_router();
        post_write_page(&router, "default", "scratch", "notes/a.md", "fine").await;
        let ws_dir = std::fs::read_dir(tmp.path().join("wiki"))
            .unwrap()
            .flatten()
            .map(|e| e.path())
            .find(|p| p.is_dir() && p.file_name().is_none_or(|n| n != ".git"))
            .unwrap();
        let proj_dir = std::fs::read_dir(&ws_dir)
            .unwrap()
            .flatten()
            .map(|e| e.path())
            .find(|p| p.is_dir())
            .unwrap();
        // Typed manifest (what the fixed backfill writes) + a pending
        // sidecar with no frontmatter (what staging writes).
        std::fs::write(
            proj_dir.join("_meta.md"),
            "---\nproject: scratch\ntype: Scope Manifest\n---\n",
        )
        .unwrap();
        std::fs::create_dir_all(proj_dir.join("_pending/auto-improve")).unwrap();
        std::fs::write(
            proj_dir.join("_pending/auto-improve/proposal.md"),
            "# A staged proposal\n\nno frontmatter at all",
        )
        .unwrap();

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/export-okf?workspace=default&project=scratch")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
            .await
            .unwrap();
        let dec = flate2::read::GzDecoder::new(std::io::Cursor::new(bytes.to_vec()));
        let mut ar = tar::Archive::new(dec);
        let names: Vec<String> = ar
            .entries()
            .unwrap()
            .map(|e| e.unwrap().path().unwrap().display().to_string())
            .collect();
        assert!(names.iter().any(|n| n == "_meta.md"), "{names:?}");
        assert!(
            !names.iter().any(|n| n.starts_with("_pending")),
            "pending sidecars must not ship: {names:?}"
        );
    }

    /// The project root of any store that ever captured an observation
    /// holds a rotated hook ledger (`log-YYYY-MM.md`, no frontmatter).
    /// It is raw capture, not a concept file: the export drops it the
    /// way it already drops `log.md`, instead of failing the whole
    /// bundle on the conformance gate (#748). Both shapes are covered —
    /// a bare ledger and one the OKF migration stamped frontmatter onto.
    #[tokio::test]
    async fn export_okf_skips_the_rotated_event_ledger() {
        let (tmp, router) = read_page_test_router();
        post_write_page(&router, "default", "scratch", "notes/a.md", "fine").await;
        let proj_dir = scratch_project_dir(tmp.path());
        std::fs::write(
            proj_dir.join("log-2026-08.md"),
            "## [2026-08-01T00:00:00Z] session_start | opened scratch\n",
        )
        .unwrap();
        std::fs::write(
            proj_dir.join("log-2026-07.md"),
            "---\ntype: Note\n---\n\n## [2026-07-01T00:00:00Z] session_start | opened scratch\n",
        )
        .unwrap();

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/export-okf?workspace=default&project=scratch")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
            .await
            .unwrap();
        let dec = flate2::read::GzDecoder::new(std::io::Cursor::new(bytes.to_vec()));
        let mut ar = tar::Archive::new(dec);
        let names: Vec<String> = ar
            .entries()
            .unwrap()
            .map(|e| e.unwrap().path().unwrap().display().to_string())
            .collect();
        assert!(names.iter().any(|n| n == "notes/a.md"), "{names:?}");
        assert!(
            !names.iter().any(|n| n.starts_with("log-")),
            "raw event ledgers must not ship: {names:?}"
        );
    }

    /// End-to-end companion to the hand-written ledger test above: the
    /// export must drop the ledger the REAL capture path produces, not
    /// merely a file whose bytes a test typed by hand. #748 was exactly a
    /// disagreement between two subsystems — the hook that appends
    /// `log-YYYY-MM.md` and the export that walked it — so the regression
    /// is only truly guarded when the ledger under test is the one
    /// `ai_memory_hooks::log::append_event` itself writes, named for the
    /// event's own month.
    #[tokio::test]
    async fn export_okf_skips_the_ledger_real_capture_writes() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let router = admin_router(admin_state_for_store(&tmp, &store, wiki.clone()));

        // A real knowledge page, created through the normal write path.
        post_write_page(&router, "default", "scratch", "notes/a.md", "fine").await;

        // The rotated ledger, created the way capture creates it: the exact
        // `append_event` the hook router calls, which names the file for the
        // event's own month (`log-YYYY-MM.md`) and writes a frontmatter-less
        // `## [ts] ...` entry.
        let scope = lookup_existing_scope(&store.reader, "default", "scratch")
            .await
            .unwrap();
        ai_memory_hooks::log::append_event(
            &wiki,
            scope.workspace_id,
            scope.project_id,
            jiff::Timestamp::now(),
            ai_memory_hooks::HookEvent::SessionStart,
            "opened scratch",
        )
        .unwrap();

        // Guard against a vacuous pass: capture must actually have written a
        // rotated ledger into the project root the export walks.
        let proj_root = wiki.project_root(scope.workspace_id, scope.project_id);
        assert!(
            std::fs::read_dir(&proj_root)
                .unwrap()
                .flatten()
                .any(|e| e.file_name().to_string_lossy().starts_with("log-")),
            "capture must have written a rotated ledger for the test to be meaningful"
        );

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/export-okf?workspace=default&project=scratch")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        // Export succeeds instead of aborting on the frontmatter-less ledger.
        assert_eq!(resp.status(), StatusCode::OK);
        let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
            .await
            .unwrap();
        let dec = flate2::read::GzDecoder::new(std::io::Cursor::new(bytes.to_vec()));
        let mut ar = tar::Archive::new(dec);
        let names: Vec<String> = ar
            .entries()
            .unwrap()
            .map(|e| e.unwrap().path().unwrap().display().to_string())
            .collect();
        assert!(
            names.iter().any(|n| n == "notes/a.md"),
            "the real knowledge page must ship: {names:?}"
        );
        assert!(
            !names.iter().any(|n| n.starts_with("log-")),
            "the ledger real capture wrote must not ship: {names:?}"
        );
    }

    /// Content gate control for #748: the ledger carve-out keys off the
    /// body, so an ordinary page named like a ledger is still a page —
    /// it ships in the bundle, and it still has to declare a `type`.
    #[tokio::test]
    async fn export_okf_still_conforms_a_prose_page_named_like_a_ledger() {
        let (tmp, router) = read_page_test_router();
        post_write_page(&router, "default", "scratch", "notes/a.md", "fine").await;
        let proj_dir = scratch_project_dir(tmp.path());
        std::fs::write(
            proj_dir.join("log-2026-09.md"),
            "---\ntitle: September log\n---\n\nProse about last month, not hook output.\n",
        )
        .unwrap();

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/export-okf?workspace=default&project=scratch")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::UNPROCESSABLE_ENTITY);
    }

    /// The single project scope dir under a freshly seeded `scratch`
    /// store. The wiki root also holds `.git`, and `read_dir` order is
    /// arbitrary, so the UUID-named scope dirs are selected explicitly.
    fn scratch_project_dir(data_dir: &std::path::Path) -> std::path::PathBuf {
        let uuid_dir = |parent: &std::path::Path| {
            std::fs::read_dir(parent)
                .unwrap()
                .flatten()
                .map(|e| e.path())
                .find(|p| p.is_dir() && p.file_name().is_none_or(|n| n != ".git"))
                .expect("scope dir")
        };
        uuid_dir(&uuid_dir(&data_dir.join("wiki")))
    }

    /// Restoring the pre-OKF checkpoint every migrated install carries must
    /// not reintroduce a pre-migration file: the restore writes the page to
    /// disk, and `export-okf` reads the disk, so a verbatim restore refuses
    /// every later export of that project with "run the server once to
    /// migrate" — advice the one-shot wiki migration will never act on again.
    #[tokio::test]
    async fn export_okf_survives_a_restore_from_a_pre_okf_checkpoint() {
        let (tmp, router) = read_page_test_router();
        post_write_page(&router, "default", "scratch", "notes/a.md", "fine").await;
        // A pre-migration file, checkpointed exactly as the OKF migration's
        // own git checkpoint captured one.
        let proj_dir = scratch_project_dir(tmp.path());
        let legacy = proj_dir.join("notes/legacy.md");
        std::fs::write(&legacy, "---\ntitle: Legacy\n---\nno type here").unwrap();
        let pre_okf_rev = post_commit(&router, "pre-okf-migration checkpoint").await;
        // Then the migration conformed it, so the export works today.
        std::fs::write(
            &legacy,
            "---\ntype: Note\ntitle: Legacy\ngenerated:\n  at: \"2026-09-01T00:00:00Z\"\n---\nno type here",
        )
        .unwrap();
        post_commit(&router, "okf-migration: conform wiki to OKF v0.2").await;
        assert_eq!(export_okf_status(&router).await, StatusCode::OK);

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/restore-page")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "workspace": "default",
                            "project": "scratch",
                            "path": "notes/legacy.md",
                            "rev": pre_okf_rev,
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK, "restore-page failed");

        assert_eq!(
            export_okf_status(&router).await,
            StatusCode::OK,
            "a restored page left the bundle non-conformant, permanently \
             breaking export-okf for this project"
        );
    }

    /// An already-conformant page restores to the same bytes it was
    /// checkpointed with: conforming the restore must not rewrite history
    /// that needed no rewriting.
    #[tokio::test]
    async fn restoring_a_conformant_page_keeps_the_checkpointed_bytes() {
        let (tmp, router) = read_page_test_router();
        post_write_page(&router, "default", "scratch", "notes/a.md", "first").await;
        let proj_dir = scratch_project_dir(tmp.path());
        let page = proj_dir.join("notes/a.md");
        let checkpointed = std::fs::read(&page).unwrap();
        let rev = post_commit(&router, "checkpoint").await;

        post_write_page(&router, "default", "scratch", "notes/a.md", "second").await;
        post_commit(&router, "later").await;
        assert_ne!(std::fs::read(&page).unwrap(), checkpointed);

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/restore-page")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "workspace": "default",
                            "project": "scratch",
                            "path": "notes/a.md",
                            "rev": rev,
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK, "restore-page failed");

        assert_eq!(
            std::fs::read(&page).unwrap(),
            checkpointed,
            "restoring an already-conformant page rewrote its bytes"
        );
    }

    /// The same promise when the checkpoint is older than the restore: the
    /// test above passes only when its writes and the restore fall in one
    /// second, because the restore used to inherit `generated.at` from the
    /// file it replaces and otherwise stamped the current time.
    #[tokio::test]
    async fn restoring_an_old_conformant_page_keeps_its_generated_at() {
        let (tmp, router) = read_page_test_router();
        post_write_page(&router, "default", "scratch", "notes/a.md", "first").await;
        let proj_dir = scratch_project_dir(tmp.path());
        let page = proj_dir.join("notes/a.md");
        let written = std::fs::read_to_string(&page).unwrap();
        let at_line = written
            .lines()
            .find(|line| line.trim_start().starts_with("at: "))
            .unwrap_or_else(|| panic!("no generated.at line in:\n{written}"));
        let indent = &at_line[..at_line.len() - at_line.trim_start().len()];
        let checkpointed =
            written.replacen(at_line, &format!("{indent}at: 2026-09-01T00:00:00Z"), 1);
        std::fs::write(&page, &checkpointed).unwrap();
        let rev = post_commit(&router, "checkpoint").await;

        post_write_page(&router, "default", "scratch", "notes/a.md", "second").await;
        post_commit(&router, "later").await;

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/restore-page")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "workspace": "default",
                            "project": "scratch",
                            "path": "notes/a.md",
                            "rev": rev,
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK, "restore-page failed");

        assert_eq!(
            std::fs::read_to_string(&page).unwrap(),
            checkpointed,
            "the restore re-stamped generated.at instead of keeping the checkpoint's"
        );
    }

    /// `POST /admin/commit`, returning the oid of the resulting HEAD
    /// checkpoint. A write-page already checkpoints itself, so the commit
    /// here may legitimately have nothing left to stage.
    async fn post_commit(router: &Router, message: &str) -> String {
        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/commit")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({ "message": message })).unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK, "commit setup failed");
        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("GET")
                    .uri("/admin/checkpoints?limit=1")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK, "checkpoint listing failed");
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        json[0]["oid"]
            .as_str()
            .expect("at least one checkpoint")
            .to_string()
    }

    /// Status of `POST /admin/export-okf` for the seeded scratch project.
    async fn export_okf_status(router: &Router) -> StatusCode {
        router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/export-okf?workspace=default&project=scratch")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap()
            .status()
    }

    /// A bundle with a non-conformant page must fail the export rather
    /// than ship something a strict reader rejects.
    #[tokio::test]
    async fn export_okf_refuses_a_nonconformant_page() {
        let (tmp, router) = read_page_test_router();
        post_write_page(&router, "default", "scratch", "notes/a.md", "fine").await;
        // Fabricate a pre-migration file next to it.
        let proj_dir = scratch_project_dir(tmp.path());
        std::fs::write(
            proj_dir.join("notes/legacy.md"),
            "---\ntitle: Legacy\n---\nno type here",
        )
        .unwrap();

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/export-okf?workspace=default&project=scratch")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::UNPROCESSABLE_ENTITY);
    }

    fn admin_state_for_store(tmp: &TempDir, store: &Store, wiki: Wiki) -> AdminState {
        admin_state_for_store_with_llm(tmp, store, wiki, None)
    }

    fn admin_state_for_store_with_llm(
        tmp: &TempDir,
        store: &Store,
        wiki: Wiki,
        llm: Option<Arc<dyn LlmProvider>>,
    ) -> AdminState {
        AdminState {
            ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),
            mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),
            writer: store.writer.clone(),
            reader: store.reader.clone(),
            wiki,
            llm,
            auto_improve_require_approval: false,
            auto_improve_review_config: Default::default(),
            embedder: None,
            provider_health: ProviderHealth::default(),
            decay_params: DecayParams::default(),
            contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
            contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
            data_dir: tmp.path().to_path_buf(),
            db_path: store.db_path().to_path_buf(),
            bind: "127.0.0.1:49374".to_string(),
            home_dir: None,
            bootstrap_lock: Arc::new(tokio::sync::Mutex::new(())),
            token_pepper: None,
            active_project: ai_memory_core::ActiveProject::new(),
            scope_invalidator: None,
            trusted_proxy_identity: false,
        }
    }

    async fn stage_pending_write(
        store: &Store,
        workspace: &str,
        project: &str,
        path: &str,
        body: &str,
    ) -> (WorkspaceId, ProjectId, AutoImproveProposalId) {
        let ws = store
            .writer
            .get_or_create_workspace(workspace)
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, project, None)
            .await
            .unwrap();
        let staged = store
            .writer
            .stage_auto_improve_run(StageAutoImproveRun {
                workspace_id: ws,
                project_id: proj,
                session_id: None,
                provider: Some("test".into()),
                model: Some("model".into()),
                summary: Some("summary".into()),
                warnings_json: serde_json::json!([]),
                rejected_candidates_json: serde_json::json!([]),
                config_json: serde_json::json!({"mode":"stage"}),
                proposal_actor: ai_memory_core::ActorContext {
                    agent: Some("auto_improve".into()),
                    ..ai_memory_core::ActorContext::default()
                },
                proposals: vec![NewAutoImproveProposal {
                    operation: AutoImproveProposalOperation::Create,
                    target_path: PagePath::new(path).unwrap(),
                    kind: "note".into(),
                    title: "Pending title".into(),
                    confidence: 0.9,
                    rationale: "rationale".into(),
                    evidence_json: serde_json::json!([{"source":"test"}]),
                    body_markdown: body.into(),
                    artifact_sha256: None,
                    edit_mode: None,
                    patch_json: None,
                    expected_base_body_sha256: None,
                }],
            })
            .await
            .unwrap();
        (ws, proj, staged.proposal_ids[0])
    }

    async fn post_write_page(router: &Router, ws: &str, project: &str, path: &str, body: &str) {
        post_write_page_with_actor(router, ws, project, path, body, None).await;
    }

    async fn post_write_page_with_actor(
        router: &Router,
        ws: &str,
        project: &str,
        path: &str,
        body: &str,
        actor: Option<&'static str>,
    ) {
        let req_body = serde_json::json!({
            "workspace": ws,
            "project": project,
            "path": path,
            "body": body,
            "title": "Read-back fixture",
        });
        let mut builder = Request::builder()
            .method("POST")
            .uri("/admin/write-page")
            .header("content-type", "application/json");
        if let Some(user) = actor {
            builder = builder.extension(ai_memory_core::ActorContext {
                user: Some(user.into()),
                ..ai_memory_core::ActorContext::default()
            });
        }
        let resp = router
            .clone()
            .oneshot(
                builder
                    .body(Body::from(serde_json::to_vec(&req_body).unwrap()))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK, "write-page setup failed");
    }

    #[tokio::test]
    async fn admin_write_page_refuses_git_reserved_and_non_portable_paths() {
        let (_tmp, router) = read_page_test_router();
        for bad in [
            ".git",
            ".git/config",
            "notes/.git",
            "notes/.git/sub.md",
            "notes/git~1",
            "notes/git~1/foo.md",
            "CON.md",
            "notes/aux.md",
            "notes/a|b.md",
        ] {
            let req_body = serde_json::json!({
                "workspace": "default",
                "project": "audit",
                "path": bad,
                "body": "bad path body",
            });
            let resp = router
                .clone()
                .oneshot(
                    Request::builder()
                        .method("POST")
                        .uri("/admin/write-page")
                        .header("content-type", "application/json")
                        .body(Body::from(serde_json::to_vec(&req_body).unwrap()))
                        .unwrap(),
                )
                .await
                .unwrap();
            assert_eq!(
                resp.status(),
                StatusCode::UNPROCESSABLE_ENTITY,
                "expected 422 for {bad:?}"
            );
        }
    }

    #[tokio::test]
    async fn read_page_path_mode_returns_full_body() {
        let (_tmp, router) = read_page_test_router();
        post_write_page(&router, "default", "audit", "notes/foo.md", "hello body").await;

        let resp = router
            .oneshot(
                Request::builder()
                    .uri("/admin/read-page?workspace=default&project=audit&path=notes/foo.md")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(json["path"], "notes/foo.md");
        assert_eq!(json["title"], "Read-back fixture");
        assert!(
            json["body"]
                .as_str()
                .unwrap_or_default()
                .contains("hello body"),
            "body must round-trip; got {:?}",
            json["body"]
        );
        assert_eq!(json["workspace"], "default");
        assert_eq!(json["project"], "audit");
    }

    #[tokio::test]
    async fn auto_improve_requires_llm_provider() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        store
            .writer
            .get_or_create_project(ws, "audit", None)
            .await
            .unwrap();
        let router = admin_router(admin_state_for_store(&tmp, &store, wiki));

        let resp = router
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/auto-improve")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "workspace": "default",
                            "project": "audit",
                            "session_id": "00000000-0000-0000-0000-000000000000"
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::SERVICE_UNAVAILABLE);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert!(
            json["error"]
                .as_str()
                .unwrap_or_default()
                .contains("LLM provider not configured")
        );
    }

    #[tokio::test]
    async fn auto_improve_missing_scope_does_not_fall_back_before_llm_check() {
        let (_tmp, router) = read_page_test_router();

        let resp = router
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/auto-improve")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "workspace": "missing",
                            "project": "missing",
                            "session_id": "00000000-0000-0000-0000-000000000000"
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::NOT_FOUND);
    }

    #[tokio::test]
    async fn audit_contamination_partial_scope_fails_closed() {
        let (_tmp, router) = read_page_test_router();

        for uri in [
            "/admin/audit-contamination?workspace=default",
            "/admin/audit-contamination?project=ai-memory",
        ] {
            let resp = router
                .clone()
                .oneshot(Request::builder().uri(uri).body(Body::empty()).unwrap())
                .await
                .unwrap();

            assert_eq!(resp.status(), StatusCode::BAD_REQUEST, "{uri}");
            let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
            let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
            assert!(
                json["error"]
                    .as_str()
                    .unwrap_or_default()
                    .contains("workspace and project must be provided together")
            );
        }
    }

    #[tokio::test]
    async fn auto_improve_auto_approves_by_default_and_uses_concrete_operations() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "scratch", None)
            .await
            .unwrap();

        wiki.write_page(WritePageRequest {
            workspace_id: ws,
            project_id: proj,
            path: PagePath::new("_slots/current-focus.md").unwrap(),
            frontmatter: serde_json::json!({"kind":"slot"}),
            body: "# Current Focus\n\nold focus".into(),
            tier: Tier::Working,
            pinned: false,
            title: Some("Current Focus".into()),
            admission_ctx: None,
            author_id: None,
            actor: ai_memory_core::ActorContext::anonymous(),
            evidence: Vec::new(),
        })
        .await
        .unwrap();

        let session_id = SessionId::new();
        store
            .writer
            .begin_session(NewSession {
                occurred_at: None,
                id: session_id,
                workspace_id: ws,
                project_id: proj,
                agent_kind: AgentKind::Other,
                cwd: None,
                actor_user: None,
            })
            .await
            .unwrap();
        store
            .writer
            .insert_observation(Sanitized::new(
                NewObservation {
                    occurred_at: None,
                    session_id,
                    workspace_id: ws,
                    project_id: proj,
                    kind: ObservationKind::UserPrompt,
                    extension: None,
                    source_event: None,
                    title: "prompt".into(),
                    body: "focus changed and durable lesson".into(),
                    importance: 5,
                },
                &Sanitizer::builtin(),
            ))
            .await
            .unwrap();

        let router = admin_router(admin_state_for_store_with_llm(
            &tmp,
            &store,
            wiki,
            Some(Arc::new(FakeAutoImproveLlm)),
        ));
        let resp = router
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/auto-improve")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "workspace": "default",
                            "project": "scratch",
                            "session_id": session_id.to_string(),
                            "min_observations": 1,
                            "min_session_duration_secs": 0,
                            "min_confidence": 0.75,
                            "max_proposals_per_run": 5
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(json["approval_required"], false);
        assert_eq!(json["approval_policy"], "auto_approve");
        let proposals = json["proposals"].as_array().unwrap();
        assert_eq!(proposals.len(), 2);
        for proposal in proposals {
            assert_eq!(proposal["status"], "approved");
            assert!(proposal["page_id"].as_str().is_some());
            let path = proposal["sidecar_path"].as_str().unwrap();
            assert!(
                std::path::Path::new(path).exists(),
                "sidecar file must be written: {path}"
            );
        }

        let staged = store
            .reader
            .list_auto_improve_proposals(ws, proj, Some(AutoImproveProposalStatus::Approved), 10)
            .await
            .unwrap();
        assert_eq!(staged.len(), 2, "DB proposal rows must be approved");
        let slot = staged
            .iter()
            .find(|p| p.target_path.as_str() == "_slots/current-focus.md")
            .expect("slot proposal staged");
        let note = staged
            .iter()
            .find(|p| p.target_path.as_str() == "notes/new-auto-improve.md")
            .expect("note proposal staged");
        assert_eq!(slot.operation, AutoImproveProposalOperation::Update);
        assert_eq!(note.operation, AutoImproveProposalOperation::Create);

        let existing = store
            .reader
            .page_body_by_ids(ws, proj, "_slots/current-focus.md")
            .await
            .unwrap()
            .expect("existing target remains present");
        assert_eq!(existing.body, "# Current Focus\n\nupdated focus proposal");
        let note_page = store
            .reader
            .page_body_by_ids(ws, proj, "notes/new-auto-improve.md")
            .await
            .unwrap()
            .expect("auto-approve writes absent target page");
        assert_eq!(
            note_page.body,
            "# New Auto Improve Lesson\n\nnew page proposal"
        );
    }

    /// The V42 staging bucket is keyed on
    /// [`ai_memory_core::ActorContext::identity_key`] through
    /// [`ai_memory_core::owner_identity`], not on `actor.user`, so an operator
    /// identified by a complete OIDC issuer/subject pair lands in an
    /// issuer-qualified bucket rather than the unattributed one. The
    /// `memory_auto_improve` MCP tool computes the same bucket, and the V42
    /// one-pending-per-target promise is what breaks when it does.
    #[tokio::test]
    async fn auto_improve_buckets_an_oidc_operator_by_qualified_identity() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "scratch", None)
            .await
            .unwrap();

        wiki.write_page(WritePageRequest {
            workspace_id: ws,
            project_id: proj,
            path: PagePath::new("_slots/current-focus.md").unwrap(),
            frontmatter: serde_json::json!({"kind":"slot"}),
            body: "# Current Focus\n\nold focus".into(),
            tier: Tier::Working,
            pinned: false,
            title: Some("Current Focus".into()),
            admission_ctx: None,
            author_id: None,
            actor: ai_memory_core::ActorContext::anonymous(),
            evidence: Vec::new(),
        })
        .await
        .unwrap();

        let session_id = SessionId::new();
        store
            .writer
            .begin_session(NewSession {
                occurred_at: None,
                id: session_id,
                workspace_id: ws,
                project_id: proj,
                agent_kind: AgentKind::Other,
                cwd: None,
                actor_user: None,
            })
            .await
            .unwrap();
        store
            .writer
            .insert_observation(Sanitized::new(
                NewObservation {
                    occurred_at: None,
                    session_id,
                    workspace_id: ws,
                    project_id: proj,
                    kind: ObservationKind::UserPrompt,
                    extension: None,
                    source_event: None,
                    title: "prompt".into(),
                    body: "focus changed and durable lesson".into(),
                    importance: 5,
                },
                &Sanitizer::builtin(),
            ))
            .await
            .unwrap();

        // A trusted proxy is configured, so the deployment distinguishes its
        // operators even with no `users` rows — which is exactly the case where
        // reaching for `actor.user` sees nobody.
        let mut state =
            admin_state_for_store_with_llm(&tmp, &store, wiki, Some(Arc::new(FakeAutoImproveLlm)));
        state.trusted_proxy_identity = true;
        let router = admin_router(state);

        let mut req = Request::builder()
            .method("POST")
            .uri("/admin/auto-improve")
            .header("content-type", "application/json")
            .body(Body::from(
                serde_json::to_vec(&serde_json::json!({
                    "workspace": "default",
                    "project": "scratch",
                    "session_id": session_id.to_string(),
                    "min_observations": 1,
                    "min_session_duration_secs": 0,
                    "min_confidence": 0.75,
                    "max_proposals_per_run": 5
                }))
                .unwrap(),
            ))
            .unwrap();
        req.extensions_mut().insert(ai_memory_core::ActorContext {
            issuer: Some("https://issuer.example".into()),
            sub: Some("subject-42".into()),
            ..ai_memory_core::ActorContext::anonymous()
        });
        req.extensions_mut().insert(ai_memory_core::AuthLevel::Root);

        let resp = router.oneshot(req).await.unwrap();
        assert_eq!(resp.status(), StatusCode::OK);

        // The bucket the contract stamps, built through the API rather than
        // hand-written, so this test follows the encoding if it ever moves.
        let expected_bucket = ai_memory_core::IdentityKey::Subject {
            issuer: "https://issuer.example".into(),
            subject: "subject-42".into(),
        }
        .storage_key();
        let staged = store
            .reader
            .list_auto_improve_proposals(ws, proj, None, 10)
            .await
            .unwrap();
        assert!(!staged.is_empty(), "the fake LLM proposes two pages");
        for proposal in &staged {
            let detail = store
                .reader
                .auto_improve_proposal_detail_with_owner(ws, proj, proposal.id)
                .await
                .unwrap()
                .expect("staged proposal readable in its own scope");
            assert_eq!(
                detail.staged_by_actor_user.as_deref(),
                Some(expected_bucket.as_str()),
                "the subject claim is the operator, not `None`: {}",
                detail.detail.summary.target_path.as_str()
            );
            let json = serde_json::to_value(&detail).unwrap();
            assert_eq!(json["staged_by_actor_user"], expected_bucket);
            assert!(json.get("summary").is_some(), "detail fields stay flat");
            assert!(
                json.get("detail").is_none(),
                "no nested compatibility wrapper"
            );
        }
    }

    /// The admin report must name the proposals the store refused to stage.
    /// Returning only the staged ids hands the operator a successful run of
    /// N-1 proposals with no trace of the Nth — the silent drop the
    /// per-proposal skip was introduced to end.
    #[tokio::test]
    async fn auto_improve_report_names_the_proposal_a_collision_skipped() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let (ws, proj, _pending) = stage_pending_write(
            &store,
            "default",
            "scratch",
            "notes/new-auto-improve.md",
            "# New Auto Improve Lesson\n\nstaged earlier",
        )
        .await;

        wiki.write_page(WritePageRequest {
            workspace_id: ws,
            project_id: proj,
            path: PagePath::new("_slots/current-focus.md").unwrap(),
            frontmatter: serde_json::json!({"kind":"slot"}),
            body: "# Current Focus\n\nold focus".into(),
            tier: Tier::Working,
            pinned: false,
            title: Some("Current Focus".into()),
            admission_ctx: None,
            author_id: None,
            actor: ai_memory_core::ActorContext::anonymous(),
            evidence: Vec::new(),
        })
        .await
        .unwrap();

        let session_id = SessionId::new();
        store
            .writer
            .begin_session(NewSession {
                occurred_at: None,
                id: session_id,
                workspace_id: ws,
                project_id: proj,
                agent_kind: AgentKind::Other,
                cwd: None,
                actor_user: None,
            })
            .await
            .unwrap();
        store
            .writer
            .insert_observation(Sanitized::new(
                NewObservation {
                    occurred_at: None,
                    session_id,
                    workspace_id: ws,
                    project_id: proj,
                    kind: ObservationKind::UserPrompt,
                    extension: None,
                    source_event: None,
                    title: "prompt".into(),
                    body: "focus changed and durable lesson".into(),
                    importance: 5,
                },
                &Sanitizer::builtin(),
            ))
            .await
            .unwrap();

        let router = admin_router(admin_state_for_store_with_llm(
            &tmp,
            &store,
            wiki,
            Some(Arc::new(FakeAutoImproveLlm)),
        ));
        let resp = router
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/auto-improve")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "workspace": "default",
                            "project": "scratch",
                            "session_id": session_id.to_string(),
                            "min_observations": 1,
                            "min_session_duration_secs": 0,
                            "min_confidence": 0.75,
                            "max_proposals_per_run": 5
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(
            json["proposals"].as_array().unwrap().len(),
            1,
            "the sibling proposal still stages",
        );
        let skipped = json["skipped"].as_array().expect("skipped array");
        assert_eq!(skipped.len(), 1, "the collided proposal must be reported");
        assert_eq!(skipped[0]["target_path"], "notes/new-auto-improve.md");
        assert!(
            skipped[0]["reason"]
                .as_str()
                .is_some_and(|r| !r.trim().is_empty()),
            "a skipped proposal must say why: {}",
            skipped[0]
        );
    }

    /// `[auth].root_username` alone does not make a server multi-operator: the
    /// scheduler and the report handlers stage unattributed, so bucketing this
    /// call by its actor would leave TWO pending proposals for one page on a
    /// single-operator server — the collision V42 promises cannot happen.
    #[tokio::test]
    async fn single_operator_admin_auto_improve_shares_the_unattributed_bucket() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let (ws, proj, _pending) = stage_pending_write(
            &store,
            "default",
            "scratch",
            "notes/new-auto-improve.md",
            "# New Auto Improve Lesson\n\nstaged earlier",
        )
        .await;

        wiki.write_page(WritePageRequest {
            workspace_id: ws,
            project_id: proj,
            path: PagePath::new("_slots/current-focus.md").unwrap(),
            frontmatter: serde_json::json!({"kind":"slot"}),
            body: "# Current Focus\n\nold focus".into(),
            tier: Tier::Working,
            pinned: false,
            title: Some("Current Focus".into()),
            admission_ctx: None,
            author_id: None,
            actor: ai_memory_core::ActorContext::anonymous(),
            evidence: Vec::new(),
        })
        .await
        .unwrap();

        let session_id = SessionId::new();
        store
            .writer
            .begin_session(NewSession {
                occurred_at: None,
                id: session_id,
                workspace_id: ws,
                project_id: proj,
                agent_kind: AgentKind::Other,
                cwd: None,
                actor_user: None,
            })
            .await
            .unwrap();
        store
            .writer
            .insert_observation(Sanitized::new(
                NewObservation {
                    occurred_at: None,
                    session_id,
                    workspace_id: ws,
                    project_id: proj,
                    kind: ObservationKind::UserPrompt,
                    extension: None,
                    source_event: None,
                    title: "prompt".into(),
                    body: "focus changed and durable lesson".into(),
                    importance: 5,
                },
                &Sanitizer::builtin(),
            ))
            .await
            .unwrap();

        // The root actor `[auth].root_username` produces, as the auth
        // middleware would stamp it.
        let router = admin_router(admin_state_for_store_with_llm(
            &tmp,
            &store,
            wiki,
            Some(Arc::new(FakeAutoImproveLlm)),
        ))
        .layer(axum::middleware::from_fn(
            |mut req: Request<Body>, next: axum::middleware::Next| async move {
                req.extensions_mut().insert(ai_memory_core::ActorContext {
                    user: Some("the-operator".into()),
                    ..ai_memory_core::ActorContext::default()
                });
                next.run(req).await
            },
        ));
        let resp = router
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/auto-improve")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "workspace": "default",
                            "project": "scratch",
                            "session_id": session_id.to_string(),
                            "min_observations": 1,
                            "min_session_duration_secs": 0,
                            "min_confidence": 0.75,
                            "max_proposals_per_run": 5
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        let skipped = json["skipped"].as_array().expect("skipped array");
        assert_eq!(
            skipped.len(),
            1,
            "a named root operator must not open a second pending bucket for the same page"
        );
        assert_eq!(skipped[0]["target_path"], "notes/new-auto-improve.md");
    }

    #[tokio::test]
    async fn auto_improve_admin_refuses_request_eval_and_inherits_server_defaults() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "scratch", None)
            .await
            .unwrap();
        let session_id = SessionId::new();
        store
            .writer
            .begin_session(NewSession {
                occurred_at: None,
                id: session_id,
                workspace_id: ws,
                project_id: proj,
                agent_kind: AgentKind::Other,
                cwd: None,
                actor_user: None,
            })
            .await
            .unwrap();
        store
            .writer
            .insert_observation(Sanitized::new(
                NewObservation {
                    occurred_at: None,
                    session_id,
                    workspace_id: ws,
                    project_id: proj,
                    kind: ObservationKind::UserPrompt,
                    extension: None,
                    source_event: None,
                    title: "prompt".into(),
                    body: "focus changed and durable lesson".into(),
                    importance: 5,
                },
                &Sanitizer::builtin(),
            ))
            .await
            .unwrap();
        let mut state =
            admin_state_for_store_with_llm(&tmp, &store, wiki, Some(Arc::new(FakeAutoImproveLlm)));
        state.auto_improve_review_config.eval = ai_memory_consolidate::AutoImproveEvalConfig {
            enabled: true,
            command: String::new(),
            builtin: String::new(),
            timeout_secs: 1,
            targets: vec!["notes".into()],
            min_delta: 0.0,
        };
        let router = admin_router(state);

        let rejected = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/auto-improve")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "workspace": "default",
                            "project": "scratch",
                            "session_id": session_id.to_string(),
                            "min_observations": 1,
                            "min_session_duration_secs": 0,
                            "min_confidence": 0.75,
                            "max_proposals_per_run": 5,
                            "eval": {
                                "enabled": true,
                                "command": tmp.path().join("request-controlled-program").display().to_string(),
                                "timeout_secs": 1,
                                "targets": ["notes"],
                                "min_delta": 0.0
                            }
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(rejected.status(), StatusCode::UNPROCESSABLE_ENTITY);
        let body = to_bytes(rejected.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(
            json["error"],
            "auto-improve eval request field was removed; configure [auto_improve.eval] on the server"
        );

        let resp = router
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/auto-improve")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "workspace": "default",
                            "project": "scratch",
                            "session_id": session_id.to_string(),
                            "min_observations": 1,
                            "min_session_duration_secs": 0,
                            "min_confidence": 0.75,
                            "max_proposals_per_run": 5
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(json["rejected_candidates_count"], 1);
        let run_id = json["run_id"]
            .as_str()
            .unwrap()
            .parse::<ai_memory_core::AutoImproveRunId>()
            .unwrap();
        let db = rusqlite::Connection::open(store.db_path()).unwrap();
        let config: String = db.query_row(
            "SELECT config_json FROM auto_improve_runs WHERE id = ?1 AND workspace_id = ?2 AND project_id = ?3",
            rusqlite::params![run_id.as_bytes(), ws.as_bytes(), proj.as_bytes()],
            |row| row.get(0),
        ).unwrap();
        let config: serde_json::Value = serde_json::from_str(&config).unwrap();
        assert_eq!(config["eval_results"].as_array().unwrap().len(), 1);
        assert_eq!(config["eval_results"][0]["status"], "failure");
        assert!(config["eval_results"][0]["passed"].is_null());
        assert_eq!(config["eval_results"][0]["reason"], "eval command is empty");
        let proposals = json["proposals"].as_array().unwrap();
        assert_eq!(proposals.len(), 1);
        assert_eq!(
            store
                .reader
                .list_auto_improve_proposals(ws, proj, None, 10)
                .await
                .unwrap()
                .len(),
            1
        );
    }

    #[tokio::test]
    async fn auto_improve_require_approval_keeps_proposals_pending() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "scratch", None)
            .await
            .unwrap();
        let session_id = SessionId::new();
        store
            .writer
            .begin_session(NewSession {
                occurred_at: None,
                id: session_id,
                workspace_id: ws,
                project_id: proj,
                agent_kind: AgentKind::Other,
                cwd: None,
                actor_user: None,
            })
            .await
            .unwrap();
        store
            .writer
            .insert_observation(Sanitized::new(
                NewObservation {
                    occurred_at: None,
                    session_id,
                    workspace_id: ws,
                    project_id: proj,
                    kind: ObservationKind::UserPrompt,
                    extension: None,
                    source_event: None,
                    title: "prompt".into(),
                    body: "durable lesson".into(),
                    importance: 5,
                },
                &Sanitizer::builtin(),
            ))
            .await
            .unwrap();
        let mut state =
            admin_state_for_store_with_llm(&tmp, &store, wiki, Some(Arc::new(FakeAutoImproveLlm)));
        state.auto_improve_require_approval = true;
        let router = admin_router(state);

        let resp = router
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/auto-improve")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "workspace": "default",
                            "project": "scratch",
                            "session_id": session_id.to_string(),
                            "min_observations": 1,
                            "min_session_duration_secs": 0,
                            "min_confidence": 0.75,
                            "max_proposals_per_run": 5
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(json["approval_required"], true);
        assert_eq!(json["approval_policy"], "manual");
        let proposals = json["proposals"].as_array().unwrap();
        assert_eq!(proposals.len(), 2);
        assert!(proposals.iter().all(|p| p["status"] == "pending"));

        let pending = store
            .reader
            .list_auto_improve_proposals(ws, proj, Some(AutoImproveProposalStatus::Pending), 10)
            .await
            .unwrap();
        assert_eq!(pending.len(), 2);
        assert!(
            store
                .reader
                .page_body_by_ids(ws, proj, "notes/new-auto-improve.md")
                .await
                .unwrap()
                .is_none(),
            "manual approval mode must not write target pages"
        );
    }

    #[tokio::test]
    async fn auto_improve_removed_mode_fields_fail_closed() {
        let (_tmp, router) = read_page_test_router();
        let resp = router
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/auto-improve")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "workspace": "default",
                            "project": "scratch",
                            "session_id": "00000000-0000-0000-0000-000000000000",
                            "dry_run": true
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::UNPROCESSABLE_ENTITY);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert!(
            json["error"]
                .as_str()
                .unwrap_or_default()
                .contains("removed")
        );
    }

    #[tokio::test]
    async fn curator_dry_run_returns_report_and_writes_nothing() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "scratch", None)
            .await
            .unwrap();
        let router = admin_router(admin_state_for_store(&tmp, &store, wiki));

        let resp = router
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/curator")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "workspace": "default",
                            "project": "scratch"
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(json["workspace"], "default");
        assert_eq!(json["project"], "scratch");
        assert_eq!(json["dry_run"], true);
        assert!(json["findings"].as_array().unwrap().is_empty());
        assert!(
            store
                .reader
                .list_auto_improve_proposals(ws, proj, None, 10)
                .await
                .unwrap()
                .is_empty(),
            "dry-run must not stage proposals"
        );
        assert!(
            store
                .reader
                .list_pages("default", "scratch")
                .await
                .unwrap()
                .is_empty(),
            "dry-run must not write pages"
        );
    }

    #[tokio::test]
    async fn curator_stage_creates_one_report_proposal_and_approval_writes_report_only() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "scratch", None)
            .await
            .unwrap();
        let router = admin_router(admin_state_for_store(&tmp, &store, wiki));

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/curator")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "workspace": "default",
                            "project": "scratch",
                            "stage": true
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        let proposal_ids = json["proposal_ids"].as_array().unwrap();
        assert_eq!(proposal_ids.len(), 1);
        let sidecar_paths = json["sidecar_paths"].as_array().unwrap();
        assert_eq!(sidecar_paths.len(), 1);
        let sidecar_path = sidecar_paths[0].as_str().unwrap();
        assert!(std::path::Path::new(sidecar_path).exists());

        let staged = store
            .reader
            .list_auto_improve_proposals(ws, proj, Some(AutoImproveProposalStatus::Pending), 10)
            .await
            .unwrap();
        assert_eq!(staged.len(), 1);
        let summary = &staged[0];
        assert_eq!(summary.kind, "curator_report");
        assert_eq!(summary.title, "Curator Report");
        assert_eq!(summary.operation, AutoImproveProposalOperation::Create);
        assert!(summary.target_path.as_str().starts_with("notes/curator-"));
        assert!(summary.target_path.as_str().ends_with(".md"));
        assert!(
            store
                .reader
                .page_body_by_ids(ws, proj, summary.target_path.as_str())
                .await
                .unwrap()
                .is_none(),
            "stage must not write target page"
        );

        let detail = store
            .reader
            .auto_improve_proposal_detail(ws, proj, summary.id)
            .await
            .unwrap()
            .unwrap();
        assert_eq!(detail.events[0].event, "staged");
        assert_eq!(detail.events[0].actor_json["agent"], "curator");
        assert!(detail.body_markdown.starts_with("# Curator Report"));
        assert!(detail.body_markdown.contains("Report-only"));

        let approve_resp = router
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri(format!(
                        "/admin/pending-writes/{}/approve?workspace=default&project=scratch",
                        summary.id
                    ))
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(approve_resp.status(), StatusCode::OK);
        let page = store
            .reader
            .page_body_by_ids(ws, proj, summary.target_path.as_str())
            .await
            .unwrap()
            .expect("approval writes curator report page");
        assert!(page.body.starts_with("# Curator Report"));
        assert_eq!(
            store
                .reader
                .list_pages("default", "scratch")
                .await
                .unwrap()
                .len(),
            1
        );
    }

    #[tokio::test]
    async fn pending_writes_list_detail_diff_and_reject_use_stored_proposal() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let (_ws, _proj, proposal_id) = stage_pending_write(
            &store,
            "default",
            "scratch",
            "notes/pending.md",
            "# Pending\n\nproposed body",
        )
        .await;
        let router = admin_router(admin_state_for_store(&tmp, &store, wiki));

        let list_resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/admin/pending-writes?workspace=default&project=scratch")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(list_resp.status(), StatusCode::OK);
        let body = to_bytes(list_resp.into_body(), usize::MAX).await.unwrap();
        let list: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(list.as_array().unwrap().len(), 1);
        assert_eq!(list[0]["id"], proposal_id.to_string());
        assert_eq!(list[0]["status"], "pending");

        let detail_resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri(format!(
                        "/admin/pending-writes/{proposal_id}?workspace=default&project=scratch"
                    ))
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(detail_resp.status(), StatusCode::OK);
        let body = to_bytes(detail_resp.into_body(), usize::MAX).await.unwrap();
        let detail: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(detail["summary"]["target_path"], "notes/pending.md");
        assert_eq!(detail["body_markdown"], "# Pending\n\nproposed body");

        let diff_resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri(format!(
                        "/admin/pending-writes/{proposal_id}/diff?workspace=default&project=scratch"
                    ))
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(diff_resp.status(), StatusCode::OK);
        let body = to_bytes(diff_resp.into_body(), usize::MAX).await.unwrap();
        let diff: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert!(diff["diff"].as_str().unwrap().contains("proposed body"));

        let reject_resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri(format!(
                        "/admin/pending-writes/{proposal_id}/reject?workspace=default&project=scratch"
                    ))
                    .header("content-type", "application/json")
                    .extension(ai_memory_core::ActorContext {
                        user: Some("reviewer".into()),
                        ..ai_memory_core::ActorContext::default()
                    })
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({"reason":"not now"})).unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(reject_resp.status(), StatusCode::OK);
        assert!(
            store
                .reader
                .page_body_by_ids(_ws, _proj, "notes/pending.md")
                .await
                .unwrap()
                .is_none(),
            "reject must not write the target page"
        );
    }

    /// A failed read of the target page must not be rendered as a diff
    /// against an empty page: that is the same response a proposal for a page
    /// that does not exist yet gets, so a reviewer would see a create where
    /// the proposal updates an existing page.
    #[tokio::test]
    async fn pending_write_diff_surfaces_a_failed_page_read() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let (ws, proj, proposal_id) = stage_pending_write(
            &store,
            "default",
            "scratch",
            "notes/pending.md",
            "# Pending\n\nproposed body",
        )
        .await;
        let router = admin_router(admin_state_for_store(&tmp, &store, wiki));
        let request = || {
            Request::builder()
                .uri(format!(
                    "/admin/pending-writes/{proposal_id}/diff?workspace=default&project=scratch"
                ))
                .body(Body::empty())
                .unwrap()
        };

        // Control: an absent target page still diffs against an empty body.
        let resp = router.clone().oneshot(request()).await.unwrap();
        assert_eq!(resp.status(), StatusCode::OK);

        // Break only the page read; the proposal tables stay readable.
        rusqlite::Connection::open(store.db_path())
            .unwrap()
            .execute_batch("ALTER TABLE pages RENAME TO pages_unreadable")
            .unwrap();
        assert!(
            store
                .reader
                .page_body_by_ids(ws, proj, "notes/pending.md")
                .await
                .is_err(),
            "fixture must make the page read fail"
        );

        let resp = router.oneshot(request()).await.unwrap();
        assert_eq!(resp.status(), StatusCode::INTERNAL_SERVER_ERROR);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let body: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert!(body.get("diff").is_none(), "no fabricated diff: {body}");
    }

    #[tokio::test]
    async fn pending_write_approve_writes_stored_body() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let (ws, proj, proposal_id) = stage_pending_write(
            &store,
            "default",
            "scratch",
            "notes/approved.md",
            "# Stored\n\nfrom stored proposal",
        )
        .await;
        wiki.write_auto_improve_sidecar(ws, proj, proposal_id)
            .await
            .unwrap();
        let router = admin_router(admin_state_for_store(&tmp, &store, wiki));

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri(format!(
                        "/admin/pending-writes/{proposal_id}/approve?workspace=default&project=scratch"
                    ))
                    .extension(ai_memory_core::ActorContext {
                        user: Some("reviewer".into()),
                        ..ai_memory_core::ActorContext::default()
                    })
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let page = store
            .reader
            .page_body_by_ids(ws, proj, "notes/approved.md")
            .await
            .unwrap()
            .expect("approve writes target page");
        assert_eq!(page.body, "# Stored\n\nfrom stored proposal");
    }

    /// #1205: a `POST /admin/pending-writes/{id}/approve` whose `id` does
    /// not exist in the requested workspace (or belongs to a different
    /// one) must answer `404 Not Found`, not `500 Internal Server Error`.
    /// The detail and diff routes already do this through `pending_detail`
    /// -- they look the proposal up before reading it. Approve and reject
    /// skipped the lookup and let the underlying wiki method surface a
    /// 500-shaped error, which hid a not-found case from the caller and
    /// could not be distinguished from a real server fault. The fix is to
    /// thread the same `pending_detail` helper through approve/reject so
    /// the three routes agree on `400` for an unparsable id, `404` for
    /// an unknown or foreign-scope id, and `500` for any other error.
    #[tokio::test]
    async fn pending_write_approve_unknown_id_returns_404() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        // The requested scope must exist, or the scope lookup itself 404s
        // and the test never reaches the proposal lookup this regression
        // is about. Stage an unrelated write so `default/scratch` resolves.
        let (_ws, _proj, _staged_id) =
            stage_pending_write(&store, "default", "scratch", "notes/other.md", "# Other\n").await;
        let router = admin_router(admin_state_for_store(&tmp, &store, wiki));
        // The requested id is brand-new: no proposal carries it. Approve
        // must surface that as a 404, not a 500.
        let unknown_id = AutoImproveProposalId::new();

        let resp = router
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri(format!(
                        "/admin/pending-writes/{unknown_id}/approve?workspace=default&project=scratch"
                    ))
                    .extension(ai_memory_core::ActorContext {
                        user: Some("reviewer".into()),
                        ..ai_memory_core::ActorContext::default()
                    })
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            resp.status(),
            StatusCode::NOT_FOUND,
            "approve of an unknown id must be 404, not 500 (regression for #1205): {}",
            resp.status(),
        );
    }

    /// #1205: same expectation as approve, for the reject route.
    #[tokio::test]
    async fn pending_write_reject_unknown_id_returns_404() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        // Same fixture need as approve: the requested scope must exist so
        // the request reaches the proposal lookup.
        let (_ws, _proj, _staged_id) =
            stage_pending_write(&store, "default", "scratch", "notes/other.md", "# Other\n").await;
        let router = admin_router(admin_state_for_store(&tmp, &store, wiki));
        let unknown_id = AutoImproveProposalId::new();

        let resp = router
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri(format!(
                        "/admin/pending-writes/{unknown_id}/reject?workspace=default&project=scratch"
                    ))
                    .header("content-type", "application/json")
                    .extension(ai_memory_core::ActorContext {
                        user: Some("reviewer".into()),
                        ..ai_memory_core::ActorContext::default()
                    })
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({"reason":"not now"})).unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            resp.status(),
            StatusCode::NOT_FOUND,
            "reject of an unknown id must be 404, not 500 (regression for #1205): {}",
            resp.status(),
        );
    }

    /// #1205: an id that exists in another workspace must still be 404
    /// from a request scoped to a different workspace, so a caller cannot
    /// use approve/reject as a cross-scope side door.
    #[tokio::test]
    async fn pending_write_approve_foreign_scope_returns_404() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        // Stage the write in workspace `alpha`.
        let (_ws_alpha, _proj_alpha, proposal_id) = stage_pending_write(
            &store,
            "alpha",
            "scratch",
            "notes/foreign.md",
            "# Foreign
",
        )
        .await;
        // The requested scope must also exist: without it the scope lookup
        // 404s first and the test never reaches the proposal lookup that
        // #1205 is about.
        let (_ws_default, _proj_default, _own_id) =
            stage_pending_write(&store, "default", "scratch", "notes/own.md", "# Own\n").await;
        let router = admin_router(admin_state_for_store(&tmp, &store, wiki));

        // Try to approve it as if it lived in `default`. The lookup must
        // say "not found in scope" -- 404, not 200.
        let resp = router
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri(format!(
                        "/admin/pending-writes/{proposal_id}/approve?workspace=default&project=scratch"
                    ))
                    .extension(ai_memory_core::ActorContext {
                        user: Some("reviewer".into()),
                        ..ai_memory_core::ActorContext::default()
                    })
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            resp.status(),
            StatusCode::NOT_FOUND,
            "approve of a foreign-scope id must be 404, not 500 (regression for #1205): {}",
            resp.status(),
        );
    }

    /// #1205: same expectation as approve, for the reject route.
    #[tokio::test]
    async fn pending_write_reject_foreign_scope_returns_404() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let (_ws_alpha, _proj_alpha, proposal_id) = stage_pending_write(
            &store,
            "alpha",
            "scratch",
            "notes/foreign.md",
            "# Foreign\n",
        )
        .await;
        // The requested scope must also exist: without it the scope lookup
        // 404s first and the test never reaches the proposal lookup that
        // #1205 is about.
        let (_ws_default, _proj_default, _own_id) =
            stage_pending_write(&store, "default", "scratch", "notes/own.md", "# Own\n").await;
        let router = admin_router(admin_state_for_store(&tmp, &store, wiki));

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri(format!(
                        "/admin/pending-writes/{proposal_id}/reject?workspace=alpha&project=scratch"
                    ))
                    .header("content-type", "application/json")
                    .extension(ai_memory_core::ActorContext {
                        user: Some("reviewer".into()),
                        ..ai_memory_core::ActorContext::default()
                    })
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({"reason":"not now"})).unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        // Legitimate control: rejecting the id through its own scope must
        // still succeed, so the 404 below cannot be a blanket deny.
        assert_eq!(
            resp.status(),
            StatusCode::OK,
            "reject of an in-scope id must still succeed (regression guard)",
        );

        // And the foreign-scope request returns 404.
        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri(format!(
                        "/admin/pending-writes/{proposal_id}/reject?workspace=default&project=scratch"
                    ))
                    .header("content-type", "application/json")
                    .extension(ai_memory_core::ActorContext {
                        user: Some("reviewer".into()),
                        ..ai_memory_core::ActorContext::default()
                    })
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({"reason":"not now"})).unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            resp.status(),
            StatusCode::NOT_FOUND,
            "reject of a foreign-scope id must be 404, not 500 (regression for #1205): {}",
            resp.status(),
        );
    }

    /// #1205: an unparsable id stays at 400 (the existing behaviour
    /// before this fix). Approve and reject must not regress to 500.
    #[tokio::test]
    async fn pending_write_approve_unparsable_id_returns_400() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let router = admin_router(admin_state_for_store(&tmp, &store, wiki));

        let resp = router
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/pending-writes/not-a-uuid/approve?workspace=default&project=scratch")
                    .extension(ai_memory_core::ActorContext {
                        user: Some("reviewer".into()),
                        ..ai_memory_core::ActorContext::default()
                    })
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::BAD_REQUEST);
    }

    /// #1205: same for the reject route.
    #[tokio::test]
    async fn pending_write_reject_unparsable_id_returns_400() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let router = admin_router(admin_state_for_store(&tmp, &store, wiki));

        let resp = router
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri(
                        "/admin/pending-writes/not-a-uuid/reject?workspace=default&project=scratch",
                    )
                    .header("content-type", "application/json")
                    .extension(ai_memory_core::ActorContext {
                        user: Some("reviewer".into()),
                        ..ai_memory_core::ActorContext::default()
                    })
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({"reason":"not now"})).unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::BAD_REQUEST);
    }

    #[tokio::test]
    async fn read_page_missing_path_returns_404() {
        let (_tmp, router) = read_page_test_router();

        let resp = router
            .oneshot(
                Request::builder()
                    .uri("/admin/read-page?workspace=default&project=audit&path=notes/nope.md")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::NOT_FOUND);
    }

    #[tokio::test]
    async fn read_page_traversal_rejected_with_400() {
        let (_tmp, router) = read_page_test_router();

        let resp = router
            .oneshot(
                Request::builder()
                    .uri("/admin/read-page?workspace=default&project=audit&path=../etc/passwd")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::BAD_REQUEST);
    }

    #[tokio::test]
    async fn read_page_without_path_or_query_returns_400() {
        let (_tmp, router) = read_page_test_router();

        let resp = router
            .oneshot(
                Request::builder()
                    .uri("/admin/read-page?workspace=default&project=audit")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::BAD_REQUEST);
    }

    /// Bug E regression: purge deletes the project's DB rows first, so by the
    /// time the admission chain fires, name-resolution from the (now gone)
    /// project row would yield an empty name and a name-based mirror would
    /// purge the wrong path. The handler must seed the admission context with
    /// the request's workspace/project names. We capture the `purge_project`
    /// webhook and assert it carries the real project name.
    #[tokio::test]
    async fn purge_project_admission_carries_the_project_name() {
        use ai_memory_wiki::{AdmissionChain, FailurePolicy, WebhookConfig};
        use axum::http::HeaderMap;
        use axum::routing::post;
        use std::sync::Mutex;

        let captured: Arc<Mutex<Option<String>>> = Arc::new(Mutex::new(None));
        let cap = captured.clone();
        let app = Router::new().route(
            "/sync",
            post(
                move |headers: HeaderMap, Json(payload): Json<serde_json::Value>| {
                    let cap = cap.clone();
                    async move {
                        if headers.get("X-Memory-Op").and_then(|v| v.to_str().ok())
                            == Some("purge_project")
                        {
                            *cap.lock().unwrap() = Some(
                                payload["ctx"]["project"]
                                    .as_str()
                                    .unwrap_or_default()
                                    .to_string(),
                            );
                        }
                        StatusCode::NO_CONTENT
                    }
                },
            ),
        );
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let base = format!("http://{}", listener.local_addr().unwrap());
        tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
        tokio::time::sleep(std::time::Duration::from_millis(20)).await;

        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let chain = AdmissionChain::new(vec![WebhookConfig {
            name: "mirror".into(),
            url: format!("{base}/sync"),
            timeout_ms: 2_000,
            failure_policy: FailurePolicy::Ignore,
            events: vec![AdmissionOp::WritePage, AdmissionOp::PurgeProject],
            blocking: true,
        }])
        .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_admission_chain(chain)
            .with_store_reader(store.reader.clone());
        let router = admin_router(AdminState {
            ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),
            mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),
            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: ProviderHealth::default(),
            decay_params: DecayParams::default(),
            contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
            contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
            data_dir: tmp.path().to_path_buf(),
            db_path: store.db_path().to_path_buf(),
            bind: "127.0.0.1:49374".to_string(),
            home_dir: None,
            bootstrap_lock: Arc::new(tokio::sync::Mutex::new(())),
            token_pepper: None,
            active_project: ai_memory_core::ActiveProject::new(),
            scope_invalidator: None,
            trusted_proxy_identity: false,
        });

        post_write_page(&router, "default", "doomed", "notes/x.md", "bye").await;

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/purge-project")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "workspace": "default",
                            "project": "doomed",
                            "confirm": true,
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK, "purge should succeed");

        // Let the async notify land.
        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
        assert_eq!(
            captured.lock().unwrap().as_deref(),
            Some("doomed"),
            "purge admission must carry the real project name, not an empty/_unscoped placeholder"
        );
    }

    /// Scope-guard / attribution regression: a destructive admin op must carry
    /// the authenticated actor into the admission context, so a scope-guard
    /// webhook can authorize by user. In prod a purge ran with an empty actor
    /// (`AdmissionContext { ..Default::default() }`) and scope-guard rejected it
    /// with `403 user '' not allowed to purge_project`.
    #[tokio::test]
    async fn purge_project_admission_carries_the_actor() {
        use ai_memory_core::ActorContext;
        use ai_memory_wiki::{AdmissionChain, FailurePolicy, WebhookConfig};
        use axum::http::HeaderMap;
        use axum::routing::post;
        use std::sync::Mutex;

        let captured: Arc<Mutex<Option<String>>> = Arc::new(Mutex::new(None));
        let cap = captured.clone();
        let app = Router::new().route(
            "/sync",
            post(
                move |headers: HeaderMap, Json(payload): Json<serde_json::Value>| {
                    let cap = cap.clone();
                    async move {
                        if headers.get("X-Memory-Op").and_then(|v| v.to_str().ok())
                            == Some("purge_project")
                        {
                            *cap.lock().unwrap() = Some(
                                payload["ctx"]["actor"]["user"]
                                    .as_str()
                                    .unwrap_or_default()
                                    .to_string(),
                            );
                        }
                        StatusCode::NO_CONTENT
                    }
                },
            ),
        );
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let base = format!("http://{}", listener.local_addr().unwrap());
        tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
        tokio::time::sleep(std::time::Duration::from_millis(20)).await;

        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let chain = AdmissionChain::new(vec![WebhookConfig {
            name: "mirror".into(),
            url: format!("{base}/sync"),
            timeout_ms: 2_000,
            failure_policy: FailurePolicy::Ignore,
            events: vec![AdmissionOp::WritePage, AdmissionOp::PurgeProject],
            blocking: true,
        }])
        .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_admission_chain(chain)
            .with_store_reader(store.reader.clone());
        let router = admin_router(AdminState {
            ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),
            mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),
            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: ProviderHealth::default(),
            decay_params: DecayParams::default(),
            contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
            contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
            data_dir: tmp.path().to_path_buf(),
            db_path: store.db_path().to_path_buf(),
            bind: "127.0.0.1:49374".to_string(),
            home_dir: None,
            bootstrap_lock: Arc::new(tokio::sync::Mutex::new(())),
            token_pepper: None,
            active_project: ai_memory_core::ActiveProject::new(),
            scope_invalidator: None,
            trusted_proxy_identity: false,
        });

        post_write_page(&router, "default", "doomed", "notes/x.md", "bye").await;

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/purge-project")
                    .header("content-type", "application/json")
                    .extension(ActorContext {
                        user: Some("alice".into()),
                        ..ActorContext::default()
                    })
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "workspace": "default",
                            "project": "doomed",
                            "confirm": true,
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK, "purge should succeed");

        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
        assert_eq!(
            captured.lock().unwrap().as_deref(),
            Some("alice"),
            "purge admission must carry the authenticated actor (empty actor → scope-guard 403 in prod)"
        );
    }

    /// End-to-end reproduction of the prod scope-guard scenario: a
    /// `Reject`-policy admission webhook that authorizes `purge_project` by
    /// `ctx.actor.user` (the real scope-guard shape). Before the fix the handler
    /// sent an empty actor, so the guard returned 403 and the purge 500'd; with
    /// the actor propagated, a matching user is allowed and the purge succeeds.
    /// Both branches run in one test so the second (allowed) purge returning
    /// `200` — not `404` — also proves the first (denied) purge left the project
    /// intact.
    #[tokio::test]
    async fn scope_guard_blocks_purge_without_actor_allows_with_actor() {
        use ai_memory_core::ActorContext;
        use ai_memory_wiki::{AdmissionChain, FailurePolicy, WebhookConfig};
        use axum::routing::post;

        // scope-guard emulation: allow `purge_project` only when the admission
        // payload's actor is "alice"; deny (403) otherwise.
        let app = Router::new().route(
            "/guard",
            post(|Json(payload): Json<serde_json::Value>| async move {
                if payload["ctx"]["actor"]["user"].as_str() == Some("alice") {
                    StatusCode::NO_CONTENT
                } else {
                    StatusCode::FORBIDDEN
                }
            }),
        );
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let base = format!("http://{}", listener.local_addr().unwrap());
        tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
        tokio::time::sleep(std::time::Duration::from_millis(20)).await;

        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let chain = AdmissionChain::new(vec![WebhookConfig {
            name: "scope-guard".into(),
            url: format!("{base}/guard"),
            timeout_ms: 2_000,
            failure_policy: FailurePolicy::Reject,
            events: vec![AdmissionOp::PurgeProject],
            blocking: true,
        }])
        .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_admission_chain(chain)
            .with_store_reader(store.reader.clone());
        let router = admin_router(AdminState {
            ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),
            mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),
            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: ProviderHealth::default(),
            decay_params: DecayParams::default(),
            contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
            contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
            data_dir: tmp.path().to_path_buf(),
            db_path: store.db_path().to_path_buf(),
            bind: "127.0.0.1:49374".to_string(),
            home_dir: None,
            bootstrap_lock: Arc::new(tokio::sync::Mutex::new(())),
            token_pepper: None,
            active_project: ai_memory_core::ActiveProject::new(),
            scope_invalidator: None,
            trusted_proxy_identity: false,
        });

        post_write_page(&router, "default", "doomed", "notes/x.md", "bye").await;

        let purge_req = |actor: Option<&'static str>| {
            let mut builder = Request::builder()
                .method("POST")
                .uri("/admin/purge-project")
                .header("content-type", "application/json");
            if let Some(user) = actor {
                builder = builder.extension(ActorContext {
                    user: Some(user.into()),
                    ..ActorContext::default()
                });
            }
            builder
                .body(Body::from(
                    serde_json::to_vec(&serde_json::json!({
                        "workspace": "default",
                        "project": "doomed",
                        "confirm": true,
                    }))
                    .unwrap(),
                ))
                .unwrap()
        };

        // Case A — empty actor → scope-guard 403 → handler 500, project intact.
        let denied = router.clone().oneshot(purge_req(None)).await.unwrap();
        assert_eq!(
            denied.status(),
            StatusCode::INTERNAL_SERVER_ERROR,
            "empty actor must be rejected by scope-guard (the prod bug)"
        );

        // Case B — actor=alice → scope-guard 204 → purge succeeds (200). A 200
        // here (not 404) also proves Case A left the project intact.
        let allowed = router
            .clone()
            .oneshot(purge_req(Some("alice")))
            .await
            .unwrap();
        assert_eq!(
            allowed.status(),
            StatusCode::OK,
            "matching actor must be authorized and the purge succeed"
        );
    }

    /// Merge moves copy source pages through `Wiki::write_page` before purging
    /// the source. That copy path must carry the authenticated actor too;
    /// otherwise a scope-guard webhook that gates `write_page` by user still
    /// rejects `/admin/move-project` even though purge/move admission was fixed.
    #[tokio::test]
    async fn move_project_merge_copy_admission_carries_the_actor() {
        use ai_memory_core::ActorContext;
        use ai_memory_wiki::{AdmissionChain, FailurePolicy, WebhookConfig};
        use axum::routing::post;

        let app = Router::new().route(
            "/guard",
            post(|Json(payload): Json<serde_json::Value>| async move {
                if payload["ctx"]["actor"]["user"].as_str() == Some("alice") {
                    StatusCode::NO_CONTENT
                } else {
                    StatusCode::FORBIDDEN
                }
            }),
        );
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let base = format!("http://{}", listener.local_addr().unwrap());
        tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
        tokio::time::sleep(std::time::Duration::from_millis(20)).await;

        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let chain = AdmissionChain::new(vec![WebhookConfig {
            name: "scope-guard".into(),
            url: format!("{base}/guard"),
            timeout_ms: 2_000,
            failure_policy: FailurePolicy::Reject,
            events: vec![AdmissionOp::WritePage, AdmissionOp::PurgeProject],
            blocking: true,
        }])
        .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_admission_chain(chain)
            .with_store_reader(store.reader.clone());
        let router = admin_router(AdminState {
            ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),
            mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),
            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: ProviderHealth::default(),
            decay_params: DecayParams::default(),
            contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
            contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
            data_dir: tmp.path().to_path_buf(),
            db_path: store.db_path().to_path_buf(),
            bind: "127.0.0.1:49374".to_string(),
            home_dir: None,
            bootstrap_lock: Arc::new(tokio::sync::Mutex::new(())),
            token_pepper: None,
            active_project: ai_memory_core::ActiveProject::new(),
            scope_invalidator: None,
            trusted_proxy_identity: false,
        });

        post_write_page_with_actor(
            &router,
            "src",
            "merged",
            "notes/source.md",
            "source body",
            Some("alice"),
        )
        .await;
        // Same project name in the destination workspace forces the copy-purge
        // merge path instead of the true-move path.
        post_write_page_with_actor(
            &router,
            "dst",
            "merged",
            "notes/existing.md",
            "existing body",
            Some("alice"),
        )
        .await;

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/move-project")
                    .header("content-type", "application/json")
                    .extension(ActorContext {
                        user: Some("alice".into()),
                        ..ActorContext::default()
                    })
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "from_workspace": "src",
                            "project": "merged",
                            "to_workspace": "dst",
                            "confirm": true, "allow_lossy_merge": true,
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::OK, "merge move should succeed");
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(json["merged_into_existing"], true);
        assert_eq!(json["moved_via"], "copy-purge");
        assert_eq!(json["source_purged"], true);
    }

    #[tokio::test]
    async fn move_project_guard_and_true_move_retarget_keyed_active_entries() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let active =
            ai_memory_core::ActiveProject::with_mode(ai_memory_core::ActiveProjectMode::PerActor);
        let mut state = admin_state_for_store(&tmp, &store, wiki);
        state.active_project = active.clone();
        let router = admin_router(state);

        post_write_page(&router, "src", "live", "notes/source.md", "source body").await;
        let src_ws = store
            .reader
            .find_workspace("src".to_string())
            .await
            .unwrap()
            .unwrap();
        let src_proj = store
            .reader
            .find_project(src_ws, "live".to_string())
            .await
            .unwrap()
            .unwrap();
        let actor = ai_memory_core::ActorKey {
            user: Some("alice".into()),
            session_id: Some("session-1".into()),
        };
        active.set_for(&actor, src_ws, src_proj, false);
        active.set(WorkspaceId::new(), ProjectId::new());

        let move_body = serde_json::json!({
            "from_workspace": "src",
            "project": "live",
            "to_workspace": "dst",
            "confirm": true, "allow_lossy_merge": true,
        });
        let guarded = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/move-project")
                    .header("content-type", "application/json")
                    .body(Body::from(serde_json::to_vec(&move_body).unwrap()))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(guarded.status(), StatusCode::CONFLICT);

        let forced_body = serde_json::json!({
            "from_workspace": "src",
            "project": "live",
            "to_workspace": "dst",
            "confirm": true, "allow_lossy_merge": true,
            "force": true,
        });
        let moved = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/move-project")
                    .header("content-type", "application/json")
                    .body(Body::from(serde_json::to_vec(&forced_body).unwrap()))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(moved.status(), StatusCode::OK);
        let dst_ws = store
            .reader
            .find_workspace("dst".to_string())
            .await
            .unwrap()
            .unwrap();
        assert_eq!(active.get_for(&actor), Some((dst_ws, src_proj)));
    }

    #[tokio::test]
    async fn delete_workspace_clears_single_and_keyed_active_entries() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let active =
            ai_memory_core::ActiveProject::with_mode(ai_memory_core::ActiveProjectMode::PerActor);
        let mut state = admin_state_for_store(&tmp, &store, wiki);
        state.active_project = active.clone();
        let router = admin_router(state);

        post_write_page(&router, "doomed-ws", "p", "notes/x.md", "bye").await;
        let ws = store
            .reader
            .find_workspace("doomed-ws".to_string())
            .await
            .unwrap()
            .unwrap();
        let proj = store
            .reader
            .find_project(ws, "p".to_string())
            .await
            .unwrap()
            .unwrap();
        let actor = ai_memory_core::ActorKey {
            user: Some("alice".into()),
            session_id: Some("session-1".into()),
        };
        active.set_for(&actor, ws, proj, false);
        active.set(ws, proj);

        let resp = router
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/delete-workspace")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "workspace": "doomed-ws",
                            "force": true,
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        assert!(active.get().is_none());
        assert!(active.get_for(&actor).is_none());
        assert!(!active.contains_workspace(ws));
    }

    #[tokio::test]
    async fn merge_workspace_folds_projects_and_deletes_empty_source() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let state = admin_state_for_store(&tmp, &store, wiki);
        let router = admin_router(state);

        // Two fresh projects in the source; the destination has neither.
        post_write_page(&router, "src", "alpha", "notes/a.md", "alpha body").await;
        post_write_page(&router, "src", "beta", "notes/b.md", "beta body").await;

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/merge-workspace")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "from": "src",
                            "to": "dst",
                            "confirm": true,
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(json["source_workspace_deleted"], true);
        let merged = json["projects_merged"].as_array().unwrap();
        assert_eq!(merged.len(), 2);
        // A fresh destination → each project is a lossless true-move.
        assert!(merged.iter().all(|r| r["moved_via"] == "true-move"));

        // The source workspace is gone; both projects now live under dst.
        assert!(
            store
                .reader
                .find_workspace("src".to_string())
                .await
                .unwrap()
                .is_none()
        );
        let dst_ws = store
            .reader
            .find_workspace("dst".to_string())
            .await
            .unwrap()
            .unwrap();
        assert!(
            store
                .reader
                .find_project(dst_ws, "alpha".to_string())
                .await
                .unwrap()
                .is_some()
        );
        assert!(
            store
                .reader
                .find_project(dst_ws, "beta".to_string())
                .await
                .unwrap()
                .is_some()
        );
    }

    #[tokio::test]
    async fn merge_workspace_requires_confirm() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let state = admin_state_for_store(&tmp, &store, wiki);
        let router = admin_router(state);

        post_write_page(&router, "src", "alpha", "notes/a.md", "alpha body").await;

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/merge-workspace")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "from": "src",
                            "to": "dst",
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::BAD_REQUEST);
        // Nothing moved: the source workspace + project are untouched.
        assert!(
            store
                .reader
                .find_workspace("src".to_string())
                .await
                .unwrap()
                .is_some()
        );
    }

    #[tokio::test]
    async fn merge_workspace_merges_colliding_project_by_content() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let state = admin_state_for_store(&tmp, &store, wiki);
        let router = admin_router(state);

        // `shared` exists in BOTH workspaces (different page paths) → the move
        // for that project takes the copy-purge merge path, not a true-move.
        // `solo` exists only in the source → lossless true-move.
        post_write_page(&router, "dst", "shared", "notes/dst.md", "dst body").await;
        post_write_page(&router, "src", "shared", "notes/src.md", "src body").await;
        post_write_page(&router, "src", "solo", "notes/solo.md", "solo body").await;

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/merge-workspace")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "from": "src",
                            "to": "dst",
                            "confirm": true,
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(json["source_workspace_deleted"], true);
        let merged = json["projects_merged"].as_array().unwrap();
        assert_eq!(merged.len(), 2);
        let vias: std::collections::HashSet<&str> = merged
            .iter()
            .filter_map(|r| r["moved_via"].as_str())
            .collect();
        assert!(
            vias.contains("copy-purge"),
            "the colliding project merged by copy-purge"
        );
        assert!(
            vias.contains("true-move"),
            "the solo project was a true-move"
        );

        // Source is gone; the merged `shared` project holds BOTH pages.
        assert!(
            store
                .reader
                .find_workspace("src".to_string())
                .await
                .unwrap()
                .is_none()
        );
        let pages = store.reader.list_pages("dst", "shared").await.unwrap();
        let paths: std::collections::HashSet<String> = pages.into_iter().map(|p| p.path).collect();
        assert!(paths.contains("notes/dst.md"));
        assert!(paths.contains("notes/src.md"));
    }

    fn recording_scope_invalidator(
        seen: Arc<std::sync::Mutex<Vec<ScopeInvalidation>>>,
    ) -> ScopeInvalidator {
        Arc::new(move |target| {
            let seen = seen.clone();
            Box::pin(async move {
                // Prove admin handlers await the invalidator before returning;
                // constructing and dropping this future would not record.
                tokio::task::yield_now().await;
                seen.lock().unwrap().push(target);
            })
        })
    }

    #[tokio::test]
    async fn delete_workspace_awaits_workspace_cache_invalidation() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let seen = Arc::new(std::sync::Mutex::new(Vec::new()));
        let mut state = admin_state_for_store(&tmp, &store, wiki);
        state.scope_invalidator = Some(recording_scope_invalidator(seen.clone()));
        let router = admin_router(state);

        post_write_page(&router, "doomed-ws", "p", "notes/x.md", "bye").await;
        let ws = store
            .reader
            .find_workspace("doomed-ws".to_string())
            .await
            .unwrap()
            .unwrap();

        let resp = router
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/delete-workspace")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "workspace": "doomed-ws",
                            "force": true,
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::OK);
        assert_eq!(
            *seen.lock().unwrap(),
            vec![ScopeInvalidation::Workspace(ws)]
        );
    }

    #[tokio::test]
    async fn copy_purge_move_clears_keyed_active_entries_and_awaits_project_invalidation() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let active =
            ai_memory_core::ActiveProject::with_mode(ai_memory_core::ActiveProjectMode::PerActor);
        let seen = Arc::new(std::sync::Mutex::new(Vec::new()));
        let mut state = admin_state_for_store(&tmp, &store, wiki);
        state.active_project = active.clone();
        state.scope_invalidator = Some(recording_scope_invalidator(seen.clone()));
        let router = admin_router(state);

        post_write_page(&router, "src", "merged", "notes/source.md", "source body").await;
        post_write_page(
            &router,
            "dst",
            "merged",
            "notes/existing.md",
            "existing body",
        )
        .await;
        let src_ws = store
            .reader
            .find_workspace("src".to_string())
            .await
            .unwrap()
            .unwrap();
        let src_proj = store
            .reader
            .find_project(src_ws, "merged".to_string())
            .await
            .unwrap()
            .unwrap();
        let actor = ai_memory_core::ActorKey {
            user: Some("alice".into()),
            session_id: Some("session-1".into()),
        };
        active.set_for(&actor, src_ws, src_proj, false);
        active.set(src_ws, src_proj);

        let resp = router
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/move-project")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "from_workspace": "src",
                            "project": "merged",
                            "to_workspace": "dst",
                            "confirm": true, "allow_lossy_merge": true,
                            "force": true,
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::OK);
        assert!(active.get().is_none());
        assert!(active.get_for(&actor).is_none());
        assert_eq!(
            *seen.lock().unwrap(),
            vec![ScopeInvalidation::Project(src_proj)]
        );
    }

    // ── user-management endpoints (P1.4) ──────────────────────────

    /// Test router that has a token pepper configured (so user-management
    /// endpoints don't return 503), runs the standard auth middleware
    /// upstream so `Extension<AuthLevel>` is populated, and is reachable
    /// as Root via a fixed bearer token.
    fn user_admin_test_router(root_token: &'static str) -> (TempDir, Router) {
        use ai_memory_core::ActorContext;
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        let pepper = ai_memory_store::TokenPepper::new("test-pepper-admin");
        let router = admin_router(AdminState {
            ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),
            mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),
            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: ProviderHealth::default(),
            decay_params: DecayParams::default(),
            contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
            contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
            data_dir: tmp.path().to_path_buf(),
            db_path: store.db_path().to_path_buf(),
            bind: "127.0.0.1:49374".to_string(),
            home_dir: None,
            bootstrap_lock: Arc::new(tokio::sync::Mutex::new(())),
            token_pepper: Some(pepper),
            active_project: ai_memory_core::ActiveProject::new(),
            scope_invalidator: None,
            trusted_proxy_identity: false,
        });
        // Wrap in a middleware that stamps the AuthLevel ourselves —
        // the real auth middleware lives in ai-memory-cli, and this
        // crate can't depend on it. The wrapper matches the Bearer
        // header against `root_token`: match → Root, present-but-no-
        // match → User (so we can test 403), absent → Anonymous.
        let router = router.layer(axum::middleware::from_fn(
            move |mut req: Request<Body>, next: axum::middleware::Next| async move {
                let bearer = req
                    .headers()
                    .get(axum::http::header::AUTHORIZATION)
                    .and_then(|h| h.to_str().ok())
                    .and_then(|s| s.strip_prefix("Bearer "))
                    .map(str::to_string);
                let level = match bearer.as_deref() {
                    Some(t) if t == root_token => ai_memory_core::AuthLevel::Root,
                    Some(_) => ai_memory_core::AuthLevel::User,
                    None => ai_memory_core::AuthLevel::Anonymous,
                };
                req.extensions_mut().insert(level);
                req.extensions_mut().insert(ActorContext::anonymous());
                next.run(req).await
            },
        ));
        (tmp, router)
    }

    /// Same AdminState as [`user_admin_test_router`], but AuthLevel comes from
    /// the production dual-auth Bearer lookup (`authenticate_bearer` +
    /// `api_credentials` hash), not a stub that stamps Root/User by string
    /// compare. Configured `root_token` is AuthLevel::Root; a DB native key
    /// authenticates as AuthLevel::User even when `users.role` is root.
    fn user_admin_dual_auth_router(root_token: &'static str) -> (TempDir, Router) {
        let (tmp, _store, router) = user_admin_dual_auth_router_with_store(root_token);
        (tmp, router)
    }

    /// [`user_admin_dual_auth_router`] plus the store behind it, for tests
    /// that seed rows the HTTP surface can no longer create.
    fn user_admin_dual_auth_router_with_store(
        root_token: &'static str,
    ) -> (TempDir, Store, Router) {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        let pepper = ai_memory_store::TokenPepper::new("test-pepper-admin");
        let router = admin_router(AdminState {
            ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),
            mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),
            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: ProviderHealth::default(),
            decay_params: DecayParams::default(),
            contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
            contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
            data_dir: tmp.path().to_path_buf(),
            db_path: store.db_path().to_path_buf(),
            bind: "127.0.0.1:49374".to_string(),
            home_dir: None,
            bootstrap_lock: Arc::new(tokio::sync::Mutex::new(())),
            token_pepper: Some(pepper.clone()),
            active_project: ai_memory_core::ActiveProject::new(),
            scope_invalidator: None,
            trusted_proxy_identity: false,
        });
        let auth_state = Arc::new(
            crate::auth::AuthState::new(Some(root_token.to_string())).with_multiuser(
                pepper,
                store.reader.clone(),
                store.writer.clone(),
            ),
        );
        let router = router.layer(axum::middleware::from_fn_with_state(
            auth_state,
            crate::human_auth::require_dual_auth,
        ));
        (tmp, store, router)
    }

    async fn post_disable_user(
        router: &Router,
        root_token: &str,
        username: &str,
    ) -> axum::http::Response<Body> {
        router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri(format!("/admin/users/{username}/disable"))
                    .header("authorization", format!("Bearer {root_token}"))
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap()
    }

    async fn patch_user(
        router: &Router,
        root_token: &str,
        username: &str,
        body: serde_json::Value,
    ) -> axum::http::Response<Body> {
        router
            .clone()
            .oneshot(
                Request::builder()
                    .method("PATCH")
                    .uri(format!("/admin/users/{username}"))
                    .header("content-type", "application/json")
                    .header("authorization", format!("Bearer {root_token}"))
                    .body(Body::from(serde_json::to_vec(&body).unwrap()))
                    .unwrap(),
            )
            .await
            .unwrap()
    }

    async fn post_create_human_user(
        router: &Router,
        root_token: &str,
        body: serde_json::Value,
    ) -> axum::http::Response<Body> {
        router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/human-users")
                    .header("content-type", "application/json")
                    .header("authorization", format!("Bearer {root_token}"))
                    .body(Body::from(serde_json::to_vec(&body).unwrap()))
                    .unwrap(),
            )
            .await
            .unwrap()
    }

    async fn user_token_admin_status(router: &Router, token: &str) -> StatusCode {
        router
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/admin/users")
                    .header("authorization", format!("Bearer {token}"))
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap()
            .status()
    }

    fn admin_route_samples() -> Vec<(&'static str, &'static str, serde_json::Value)> {
        vec![
            ("POST", "/admin/backup", serde_json::Value::Null),
            (
                "POST",
                "/admin/export-okf?workspace=default&project=scratch",
                serde_json::Value::Null,
            ),
            (
                "POST",
                "/admin/bootstrap",
                serde_json::json!({
                    "workspace": "default",
                    "project": "scratch",
                    "sources": [],
                    "dry_run": true
                }),
            ),
            (
                "POST",
                "/admin/auto-improve",
                serde_json::json!({
                    "workspace": "default",
                    "project": "scratch",
                    "session_id": "00000000-0000-0000-0000-000000000000",
                    "dry_run": true
                }),
            ),
            (
                "POST",
                "/admin/auto-improve/report",
                serde_json::json!({"workspace": "default", "project": "scratch"}),
            ),
            ("GET", "/admin/status", serde_json::Value::Null),
            ("POST", "/admin/llm-test", serde_json::Value::Null),
            ("GET", "/admin/metrics", serde_json::Value::Null),
            (
                "GET",
                "/admin/project-coordinate?workspace=default&project=scratch",
                serde_json::Value::Null,
            ),
            (
                "GET",
                "/admin/sessions/by-agent?workspace=default&project=scratch",
                serde_json::Value::Null,
            ),
            (
                "GET",
                "/admin/activity/by-client?since_days=7",
                serde_json::Value::Null,
            ),
            ("GET", "/admin/audit-contamination", serde_json::Value::Null),
            ("GET", "/admin/audit-log", serde_json::Value::Null),
            ("GET", "/admin/search?q=test", serde_json::Value::Null),
            ("GET", "/admin/recent", serde_json::Value::Null),
            (
                "GET",
                "/admin/read-page?workspace=default&project=scratch&path=notes/x.md",
                serde_json::Value::Null,
            ),
            ("POST", "/admin/reorg", serde_json::json!({"dry_run": true})),
            (
                "POST",
                "/admin/lint",
                serde_json::json!({"workspace": "default", "project": "scratch", "dry_run": true}),
            ),
            (
                "POST",
                "/admin/forget-sweep",
                serde_json::json!({"workspace": "default", "project": "scratch", "dry_run": true}),
            ),
            (
                "POST",
                "/admin/embed",
                serde_json::json!({"workspace": "default", "project": "scratch", "dry_run": true}),
            ),
            (
                "POST",
                "/admin/curator",
                serde_json::json!({"workspace": "default", "project": "scratch", "dry_run": true}),
            ),
            (
                "POST",
                "/admin/commit",
                serde_json::json!({"message": "test"}),
            ),
            ("GET", "/admin/checkpoints?limit=1", serde_json::Value::Null),
            (
                "GET",
                "/admin/pending-writes?workspace=default&project=scratch",
                serde_json::Value::Null,
            ),
            (
                "GET",
                "/admin/pending-writes/00000000-0000-0000-0000-000000000000?workspace=default&project=scratch",
                serde_json::Value::Null,
            ),
            (
                "GET",
                "/admin/pending-writes/00000000-0000-0000-0000-000000000000/diff?workspace=default&project=scratch",
                serde_json::Value::Null,
            ),
            (
                "POST",
                "/admin/pending-writes/00000000-0000-0000-0000-000000000000/approve?workspace=default&project=scratch",
                serde_json::Value::Null,
            ),
            (
                "POST",
                "/admin/pending-writes/00000000-0000-0000-0000-000000000000/reject?workspace=default&project=scratch",
                serde_json::json!({"reason": "no"}),
            ),
            (
                "POST",
                "/admin/restore-page",
                serde_json::json!({
                    "workspace": "default",
                    "project": "scratch",
                    "path": "notes/x.md",
                    "rev": "HEAD"
                }),
            ),
            (
                "POST",
                "/admin/purge-project",
                serde_json::json!({"workspace": "default", "project": "scratch", "confirm": true}),
            ),
            (
                "POST",
                "/admin/rename-project",
                serde_json::json!({"workspace": "default", "from": "scratch", "to": "renamed"}),
            ),
            (
                "POST",
                "/admin/move-project",
                serde_json::json!({
                    "from_workspace": "default",
                    "to_workspace": "archive",
                    "project": "scratch",
                    "confirm": true, "allow_lossy_merge": true
                }),
            ),
            (
                "POST",
                "/admin/repair-session-times",
                serde_json::json!({
                    "workspace": "default",
                    "project": "scratch",
                    "sessions": [],
                    "confirm": false
                }),
            ),
            (
                "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",
                serde_json::json!({
                    "workspace": "default",
                    "project": "scratch",
                    "path": "notes/x.md",
                    "body": "body"
                }),
            ),
            (
                "POST",
                "/admin/delete-page",
                serde_json::json!({
                    "workspace": "default",
                    "project": "scratch",
                    "path": "notes/x.md"
                }),
            ),
            ("GET", "/admin/users", serde_json::Value::Null),
            (
                "POST",
                "/admin/human-users",
                serde_json::json!({"username": "human"}),
            ),
            (
                "POST",
                "/admin/users/alice/disable",
                serde_json::Value::Null,
            ),
            ("POST", "/admin/users/alice/enable", serde_json::Value::Null),
            ("GET", "/admin/api-credentials", serde_json::Value::Null),
        ]
    }

    #[tokio::test]
    async fn multiuser_admin_routes_reject_db_user_tier() {
        let (_tmp, router) = user_admin_test_router("root-token");
        post_create_human_user(
            &router,
            "root-token",
            serde_json::json!({"username": "alice"}),
        )
        .await;

        for (method, uri, payload) in admin_route_samples() {
            let mut builder = Request::builder()
                .method(method)
                .uri(uri)
                .header("authorization", "Bearer db-user-token");
            let body = if payload.is_null() {
                Body::empty()
            } else {
                builder = builder.header("content-type", "application/json");
                Body::from(serde_json::to_vec(&payload).unwrap())
            };
            let resp = router
                .clone()
                .oneshot(builder.body(body).unwrap())
                .await
                .unwrap();
            assert_eq!(
                resp.status(),
                StatusCode::FORBIDDEN,
                "{method} {uri} must be root-only for DB users in multi-user mode"
            );
        }
    }

    #[tokio::test]
    async fn multiuser_admin_routes_reject_anonymous() {
        let (_tmp, router) = user_admin_test_router("root-token");
        post_create_human_user(
            &router,
            "root-token",
            serde_json::json!({"username": "alice"}),
        )
        .await;
        for (method, uri, payload) in admin_route_samples() {
            let mut builder = Request::builder().method(method).uri(uri);
            let body = if payload.is_null() {
                Body::empty()
            } else {
                builder = builder.header("content-type", "application/json");
                Body::from(serde_json::to_vec(&payload).unwrap())
            };
            let resp = router
                .clone()
                .oneshot(builder.body(body).unwrap())
                .await
                .unwrap();
            assert_eq!(
                resp.status(),
                StatusCode::UNAUTHORIZED,
                "{method} {uri} must require authentication in multi-user mode"
            );
        }
    }

    /// The preview branch (no `confirm`, `dry_run: true`) sits behind the
    /// exact same root-only gate as the rest of `/admin/purge-project` — it
    /// is reached through the same handler and route, so there is no
    /// separate check to forget. Mirrors
    /// `multiuser_admin_routes_reject_db_user_tier` /
    /// `multiuser_admin_routes_reject_anonymous` above, but with a payload
    /// shaped like a preview request instead of `admin_route_samples()`'s
    /// confirmed one. The root control case proves the gate — not the
    /// route — is what is being tested: root reaches the handler (answered
    /// with `404`, since this router's store has no `default/scratch`
    /// project), while the DB user and anonymous requests below never get
    /// that far.
    #[tokio::test]
    async fn multiuser_purge_project_dry_run_rejects_db_user_and_anonymous() {
        let (_tmp, router) = user_admin_test_router("root-token");
        post_create_human_user(
            &router,
            "root-token",
            serde_json::json!({"username": "alice"}),
        )
        .await;

        let preview_body = serde_json::json!({
            "workspace": "default",
            "project": "scratch",
            "confirm": false,
            "dry_run": true
        });

        // Root control case: reaches the handler (proven by getting past
        // both auth statuses below into the route's own 404 for an unknown
        // project), unlike the DB-user and anonymous requests.
        let root_resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/purge-project")
                    .header("content-type", "application/json")
                    .header("authorization", "Bearer root-token")
                    .body(Body::from(serde_json::to_vec(&preview_body).unwrap()))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            root_resp.status(),
            StatusCode::NOT_FOUND,
            "root must reach the preview handler, not be blocked by the auth gate"
        );

        let db_user_resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/purge-project")
                    .header("content-type", "application/json")
                    .header("authorization", "Bearer db-user-token")
                    .body(Body::from(serde_json::to_vec(&preview_body).unwrap()))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            db_user_resp.status(),
            StatusCode::FORBIDDEN,
            "a dry-run preview must stay root-only for DB users in multi-user mode"
        );

        let anon_resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/purge-project")
                    .header("content-type", "application/json")
                    .body(Body::from(serde_json::to_vec(&preview_body).unwrap()))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            anon_resp.status(),
            StatusCode::UNAUTHORIZED,
            "a dry-run preview must require authentication in multi-user mode"
        );
    }

    /// The `purge-session` preview branch sits behind the same root-only
    /// gate, reached through the same handler and route as the confirmed
    /// path — mirrors
    /// `multiuser_purge_project_dry_run_rejects_db_user_and_anonymous` above.
    /// The root control case proves the gate — not the route — is what is
    /// being tested: root reaches the handler (answered with `404`, since
    /// this router's store has no `default/scratch` project), while the
    /// DB user and anonymous requests below never get that far.
    #[tokio::test]
    async fn multiuser_purge_session_dry_run_rejects_db_user_and_anonymous() {
        let (_tmp, router) = user_admin_test_router("root-token");
        post_create_human_user(
            &router,
            "root-token",
            serde_json::json!({"username": "alice"}),
        )
        .await;

        let preview_body = serde_json::json!({
            "workspace": "default",
            "project": "scratch",
            "session_id": ai_memory_core::SessionId::new().to_string(),
            "confirm": false,
            "dry_run": true
        });

        let root_resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/purge-session")
                    .header("content-type", "application/json")
                    .header("authorization", "Bearer root-token")
                    .body(Body::from(serde_json::to_vec(&preview_body).unwrap()))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            root_resp.status(),
            StatusCode::NOT_FOUND,
            "root must reach the preview handler, not be blocked by the auth gate"
        );

        let db_user_resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/purge-session")
                    .header("content-type", "application/json")
                    .header("authorization", "Bearer db-user-token")
                    .body(Body::from(serde_json::to_vec(&preview_body).unwrap()))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            db_user_resp.status(),
            StatusCode::FORBIDDEN,
            "a dry-run preview must stay root-only for DB users in multi-user mode"
        );

        let anon_resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/purge-session")
                    .header("content-type", "application/json")
                    .body(Body::from(serde_json::to_vec(&preview_body).unwrap()))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            anon_resp.status(),
            StatusCode::UNAUTHORIZED,
            "a dry-run preview must require authentication in multi-user mode"
        );
    }

    /// The `delete-workspace` preview branch sits behind the same root-only
    /// gate, reached through the same handler and route as the confirmed
    /// path — mirrors `multiuser_purge_project_dry_run_rejects_db_user_and_anonymous`
    /// above.
    /// The root control case proves the gate — not the route — is what is
    /// being tested: root reaches the handler (answered with `404`, since
    /// this router's store has no `ghost-workspace`), while the DB user and
    /// anonymous requests below never get that far.
    #[tokio::test]
    async fn multiuser_delete_workspace_dry_run_rejects_db_user_and_anonymous() {
        let (_tmp, router) = user_admin_test_router("root-token");
        post_create_human_user(
            &router,
            "root-token",
            serde_json::json!({"username": "alice"}),
        )
        .await;

        let preview_body = serde_json::json!({
            "workspace": "ghost-workspace",
            "force": false,
            "dry_run": true
        });

        let root_resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/delete-workspace")
                    .header("content-type", "application/json")
                    .header("authorization", "Bearer root-token")
                    .body(Body::from(serde_json::to_vec(&preview_body).unwrap()))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            root_resp.status(),
            StatusCode::NOT_FOUND,
            "root must reach the preview handler, not be blocked by the auth gate"
        );

        let db_user_resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/delete-workspace")
                    .header("content-type", "application/json")
                    .header("authorization", "Bearer db-user-token")
                    .body(Body::from(serde_json::to_vec(&preview_body).unwrap()))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            db_user_resp.status(),
            StatusCode::FORBIDDEN,
            "a dry-run preview must stay root-only for DB users in multi-user mode"
        );

        let anon_resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/delete-workspace")
                    .header("content-type", "application/json")
                    .body(Body::from(serde_json::to_vec(&preview_body).unwrap()))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            anon_resp.status(),
            StatusCode::UNAUTHORIZED,
            "a dry-run preview must require authentication in multi-user mode"
        );
    }
    #[tokio::test]
    async fn multiuser_operational_admin_routes_allow_root() {
        let (_tmp, router) = user_admin_test_router("root-token");
        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/admin/status")
                    .header("authorization", "Bearer root-token")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/admin/metrics")
                    .header("authorization", "Bearer root-token")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        assert_eq!(
            resp.headers()[axum::http::header::CONTENT_TYPE],
            crate::metrics::PROMETHEUS_CONTENT_TYPE
        );

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/admin/activity/by-client?since_days=7")
                    .header("authorization", "Bearer root-token")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);

        // The scope does not exist in this fixture, so reaching the handler
        // produces 404. A rejected root request would instead be 401/403.
        let resp = router
            .oneshot(
                Request::builder()
                    .uri("/admin/sessions/by-agent?workspace=default&project=scratch")
                    .header("authorization", "Bearer root-token")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::NOT_FOUND);
    }

    #[tokio::test]
    async fn trusted_proxy_topology_gates_admin_without_db_users() {
        use ai_memory_core::ActorContext;

        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        let router = admin_router(AdminState {
            ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),
            mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),
            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: ProviderHealth::default(),
            decay_params: DecayParams::default(),
            contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
            contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
            data_dir: tmp.path().to_path_buf(),
            db_path: store.db_path().to_path_buf(),
            bind: "127.0.0.1:49374".to_string(),
            home_dir: None,
            bootstrap_lock: Arc::new(tokio::sync::Mutex::new(())),
            token_pepper: Some(ai_memory_store::TokenPepper::new("test-pepper-admin")),
            active_project: ai_memory_core::ActiveProject::new(),
            scope_invalidator: None,
            trusted_proxy_identity: true,
        })
        .layer(axum::middleware::from_fn(
            |mut req: Request<Body>, next: axum::middleware::Next| async move {
                let level = match req
                    .headers()
                    .get("x-test-auth-level")
                    .and_then(|value| value.to_str().ok())
                {
                    Some("root") => ai_memory_core::AuthLevel::Root,
                    Some("user") => ai_memory_core::AuthLevel::User,
                    _ => ai_memory_core::AuthLevel::Anonymous,
                };
                req.extensions_mut().insert(level);
                req.extensions_mut().insert(ActorContext::anonymous());
                next.run(req).await
            },
        ));

        for (level, expected) in [
            (None, StatusCode::UNAUTHORIZED),
            (Some("user"), StatusCode::FORBIDDEN),
            (Some("root"), StatusCode::OK),
        ] {
            let mut request = Request::builder().uri("/admin/status");
            if let Some(level) = level {
                request = request.header("x-test-auth-level", level);
            }
            let response = router
                .clone()
                .oneshot(request.body(Body::empty()).unwrap())
                .await
                .unwrap();
            assert_eq!(response.status(), expected, "level={level:?}");
        }
    }

    #[tokio::test]
    async fn admin_mode_switches_after_first_user_without_restart() {
        let (_tmp, router) = user_admin_test_router("root-token");

        let anonymous_before = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/admin/status")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(anonymous_before.status(), StatusCode::OK);

        let create = post_create_human_user(
            &router,
            "root-token",
            serde_json::json!({"username": "alice"}),
        )
        .await;
        assert_eq!(create.status(), StatusCode::OK);

        for (token, expected) in [
            (None, StatusCode::UNAUTHORIZED),
            (Some("db-user-token"), StatusCode::FORBIDDEN),
            (Some("root-token"), StatusCode::OK),
        ] {
            let mut request = Request::builder().uri("/admin/status");
            if let Some(token) = token {
                request = request.header("authorization", format!("Bearer {token}"));
            }
            let response = router
                .clone()
                .oneshot(request.body(Body::empty()).unwrap())
                .await
                .unwrap();
            assert_eq!(response.status(), expected, "token {token:?}");
        }

        let expire = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/users/alice/disable")
                    .header("authorization", "Bearer root-token")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(expire.status(), StatusCode::OK);

        let anonymous_after_expire = router
            .oneshot(
                Request::builder()
                    .uri("/admin/status")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(anonymous_after_expire.status(), StatusCode::UNAUTHORIZED);
    }

    #[tokio::test]
    async fn admin_mode_store_read_failure_fails_closed() {
        use ai_memory_core::ActorContext;

        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        let missing_db_reader =
            ai_memory_store::ReaderPool::new(&tmp.path().join("missing.sqlite"), 1).unwrap();
        let router = admin_router(AdminState {
            ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),
            mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),
            writer: store.writer.clone(),
            reader: missing_db_reader,
            wiki,
            llm: None,
            auto_improve_require_approval: false,
            auto_improve_review_config: Default::default(),
            embedder: None,
            provider_health: ProviderHealth::default(),
            decay_params: DecayParams::default(),
            contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
            contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
            data_dir: tmp.path().to_path_buf(),
            db_path: store.db_path().to_path_buf(),
            bind: "127.0.0.1:49374".to_string(),
            home_dir: None,
            bootstrap_lock: Arc::new(tokio::sync::Mutex::new(())),
            token_pepper: Some(ai_memory_store::TokenPepper::new("test-pepper-admin")),
            active_project: ai_memory_core::ActiveProject::new(),
            scope_invalidator: None,
            trusted_proxy_identity: false,
        })
        .layer(axum::middleware::from_fn(
            |mut req: Request<Body>, next: axum::middleware::Next| async move {
                req.extensions_mut()
                    .insert(ai_memory_core::AuthLevel::Anonymous);
                req.extensions_mut().insert(ActorContext::anonymous());
                next.run(req).await
            },
        ));

        let response = router
            .oneshot(
                Request::builder()
                    .uri("/admin/status")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(response.status(), StatusCode::INTERNAL_SERVER_ERROR);
        let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
        assert!(String::from_utf8_lossy(&body).contains("could not verify user configuration"));
    }

    #[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_human_user_is_additive_and_returns_temporary_password_once() {
        let (_tmp, router) = user_admin_test_router("root-token");
        let resp = post_create_human_user(
            &router,
            "root-token",
            serde_json::json!({
                "username": "alice",
                "role": "root"
            }),
        )
        .await;
        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert!(json["temporary_password"].as_str().unwrap().len() >= 12);
        assert_eq!(json["user"]["role"], "root");
        assert!(json["user"]["must_change_password"].as_bool().unwrap());
        assert!(json.get("token").is_none());
    }

    const LEGACY_TEST_PEPPER: &str = "test-pepper-admin";

    /// What a 2.x `user add` left behind once V55 copied it: a user without a
    /// password and a `legacy-user-token` credential whose id is the user id
    /// and whose secret has no `aim_` prefix.
    async fn seed_legacy_token_user(
        store: &Store,
        username: &str,
        secret: &str,
    ) -> ai_memory_core::UserId {
        let user_id = store
            .writer
            .create_human_user(
                ai_memory_core::NewUser {
                    username: username.to_string(),
                    name: None,
                    email: None,
                },
                ai_memory_core::UserRole::User,
                None,
                false,
            )
            .await
            .unwrap();
        let pepper = ai_memory_store::TokenPepper::new(LEGACY_TEST_PEPPER);
        store
            .writer
            .create_api_credential(
                ai_memory_core::ApiCredentialId::from_slice(user_id.as_bytes()).unwrap(),
                user_id,
                "legacy-user-token".to_string(),
                ai_memory_store::hash_token(secret, &pepper),
                None,
            )
            .await
            .unwrap();
        user_id
    }

    async fn issue_api_key(router: &Router, username: &str) -> String {
        let created = post_create_human_user(
            router,
            "root-token",
            serde_json::json!({ "username": username }),
        )
        .await;
        assert_eq!(created.status(), StatusCode::OK);
        let (status, json) = admin_call(
            router,
            "POST",
            "/admin/api-credentials",
            "root-token",
            Some(serde_json::json!({ "username": username, "label": "cli" })),
        )
        .await;
        assert_eq!(status, StatusCode::OK);
        json["token"].as_str().unwrap().to_string()
    }

    /// 3.0 removed the 1.x token-management endpoints. None of them may come
    /// back for any tier: root gets a routing miss, the other tiers never get
    /// past it either, and nothing about the users or their credentials
    /// changes.
    #[tokio::test]
    async fn removed_legacy_token_routes_are_gone_for_every_tier() {
        let (_tmp, store, router) = user_admin_dual_auth_router_with_store("root-token");
        let legacy = "q0N2v1d8kQd3m6Q7e9x4Zb1a2c3d4e5f6g7h8i9j0kL";
        seed_legacy_token_user(&store, "alice", legacy).await;
        let db_user = issue_api_key(&router, "bob").await;

        let removed = [
            (
                "/admin/users",
                Some(serde_json::json!({ "username": "mallory" })),
            ),
            ("/admin/users/alice/expire", None),
            ("/admin/users/alice/revive", None),
            ("/admin/users/alice/rotate-token", None),
        ];
        for (uri, body) in removed {
            for bearer in [
                Some("root-token"),
                Some(db_user.as_str()),
                Some(legacy),
                None,
            ] {
                let mut builder = Request::builder().method("POST").uri(uri);
                if let Some(token) = bearer {
                    builder = builder.header("authorization", format!("Bearer {token}"));
                }
                let request_body = match &body {
                    Some(json) => {
                        builder = builder.header("content-type", "application/json");
                        Body::from(serde_json::to_vec(json).unwrap())
                    }
                    None => Body::empty(),
                };
                let status = router
                    .clone()
                    .oneshot(builder.body(request_body).unwrap())
                    .await
                    .unwrap()
                    .status();
                let tier = match bearer {
                    Some("root-token") => "root",
                    Some(token) if token == legacy => "legacy token",
                    Some(_) => "DB user",
                    None => "anonymous",
                };
                // Root passes every gate and meets the routing miss itself:
                // 405 where GET /admin/users still owns the path, 404 for the
                // rest. Anonymous stops at authentication. On the shared
                // /admin/users path the root gate answers other tiers first.
                let expected = match (tier, uri) {
                    ("anonymous", _) => StatusCode::UNAUTHORIZED,
                    ("root", "/admin/users") => StatusCode::METHOD_NOT_ALLOWED,
                    (_, "/admin/users") => StatusCode::FORBIDDEN,
                    _ => StatusCode::NOT_FOUND,
                };
                assert_eq!(
                    status, expected,
                    "POST {uri} as {tier} must not reach a handler"
                );
            }
        }

        let (status, json) = admin_call(&router, "GET", "/admin/users", "root-token", None).await;
        assert_eq!(status, StatusCode::OK, "GET /admin/users stays mounted");
        let names: Vec<&str> = json["users"]
            .as_array()
            .unwrap()
            .iter()
            .map(|u| u["username"].as_str().unwrap())
            .collect();
        assert_eq!(names, ["alice", "bob"], "no user may be created");
        let (_, json) =
            admin_call(&router, "GET", "/admin/api-credentials", "root-token", None).await;
        for credential in json["credentials"].as_array().unwrap() {
            assert!(
                credential.get("revoked_at").is_none(),
                "no credential may be expired: {credential}"
            );
        }
        assert_eq!(
            user_token_admin_status(&router, legacy).await,
            StatusCode::FORBIDDEN,
            "the legacy token must still authenticate"
        );
    }

    /// A token issued by the removed 1.x `user add` is an ordinary API key in
    /// 3.0: it authenticates as its non-root user, an expired one stays
    /// refused, and `api-key list|rotate|revoke` manage it.
    #[tokio::test]
    async fn legacy_user_token_is_managed_as_an_api_key() {
        let (_tmp, store, router) = user_admin_dual_auth_router_with_store("root-token");
        let active = "Lw7u0Qe1r2t3y4u5i6o7p8a9s0d1f2g3h4j5k6l7z8x";
        let expired = "Mx8v1Rf2t3g4y5h6u7j8i9k0o1l2p3a4s5d6f7g8h9j";
        let alice = seed_legacy_token_user(&store, "alice", active).await;
        let carol = seed_legacy_token_user(&store, "carol", expired).await;
        // 2.x `user expire` reached `api_credentials.revoked_at` through the
        // V55 mirror; that is the state an expired token arrives in.
        store
            .writer
            .revoke_api_credential(
                ai_memory_core::ApiCredentialId::from_slice(carol.as_bytes()).unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(
            user_token_admin_status(&router, active).await,
            StatusCode::FORBIDDEN,
            "an active legacy token authenticates as a non-root DB user"
        );
        assert_eq!(
            user_token_admin_status(&router, expired).await,
            StatusCode::UNAUTHORIZED,
            "an expired legacy token stays refused"
        );

        let (status, json) =
            admin_call(&router, "GET", "/admin/api-credentials", "root-token", None).await;
        assert_eq!(status, StatusCode::OK);
        let listed = json["credentials"]
            .as_array()
            .unwrap()
            .iter()
            .find(|c| c["id"] == alice.to_string())
            .cloned()
            .expect("api-key list shows the legacy credential");
        assert_eq!(listed["label"], "legacy-user-token");
        assert_eq!(listed["user_id"], alice.to_string());
        assert!(listed.get("revoked_at").is_none());

        let (status, json) = admin_call(
            &router,
            "POST",
            &format!("/admin/api-credentials/{alice}/rotate"),
            "root-token",
            None,
        )
        .await;
        assert_eq!(status, StatusCode::OK);
        let rotated = json["token"].as_str().unwrap().to_string();
        assert!(rotated.starts_with("aim_"));
        assert_eq!(
            user_token_admin_status(&router, active).await,
            StatusCode::UNAUTHORIZED,
            "rotation retires the legacy secret"
        );
        assert_eq!(
            user_token_admin_status(&router, &rotated).await,
            StatusCode::FORBIDDEN
        );

        let (status, _) = admin_call(
            &router,
            "POST",
            &format!("/admin/api-credentials/{alice}/revoke"),
            "root-token",
            None,
        )
        .await;
        assert_eq!(status, StatusCode::OK);
        assert_eq!(
            user_token_admin_status(&router, &rotated).await,
            StatusCode::UNAUTHORIZED,
            "a revoked credential is refused"
        );
    }
    #[tokio::test]
    async fn create_user_rejects_duplicate_username_with_409() {
        let (_tmp, router) = user_admin_test_router("root-token");
        let _ = post_create_human_user(
            &router,
            "root-token",
            serde_json::json!({"username": "alice"}),
        )
        .await;
        let resp = post_create_human_user(
            &router,
            "root-token",
            serde_json::json!({"username": "alice"}),
        )
        .await;
        assert_eq!(resp.status(), StatusCode::CONFLICT);
    }

    #[tokio::test]
    async fn create_user_rejects_invalid_email_with_400() {
        let (_tmp, router) = user_admin_test_router("root-token");
        let resp = post_create_human_user(
            &router,
            "root-token",
            serde_json::json!({"username": "alice", "email": "not-an-email"}),
        )
        .await;
        assert_eq!(resp.status(), StatusCode::BAD_REQUEST);
    }

    #[tokio::test]
    async fn create_user_as_anonymous_returns_401() {
        let (_tmp, router) = user_admin_test_router("root-token");
        // No Authorization header → middleware stamps Anonymous tier.
        let resp = router
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/human-users")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({"username": "alice"})).unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::UNAUTHORIZED);
    }

    #[tokio::test]
    async fn create_user_as_user_tier_returns_403() {
        let (_tmp, router) = user_admin_test_router("root-token");
        let resp = post_create_human_user(
            &router,
            "not-the-root-token",
            serde_json::json!({"username": "alice"}),
        )
        .await;
        assert_eq!(resp.status(), StatusCode::FORBIDDEN);
    }

    #[tokio::test]
    async fn list_users_returns_added_users_in_insertion_order() {
        let (_tmp, router) = user_admin_test_router("root-token");
        for n in ["alice", "bob", "carol"] {
            let _ =
                post_create_human_user(&router, "root-token", serde_json::json!({"username": n}))
                    .await;
        }
        let resp = router
            .oneshot(
                Request::builder()
                    .uri("/admin/users")
                    .header("authorization", "Bearer root-token")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        let users = json["users"].as_array().unwrap();
        assert_eq!(users.len(), 3);
        assert_eq!(users[0]["username"], "alice");
        assert_eq!(users[1]["username"], "bob");
        assert_eq!(users[2]["username"], "carol");
        // Tokens are NEVER surfaced by the list endpoint.
        for u in users {
            assert!(
                u.get("token").is_none() && u.get("temporary_password").is_none(),
                "list must not leak secrets"
            );
        }
    }

    #[tokio::test]
    async fn disable_then_enable_round_trips() {
        let (_tmp, router) = user_admin_test_router("root-token");
        let _ = post_create_human_user(
            &router,
            "root-token",
            serde_json::json!({"username": "alice"}),
        )
        .await;

        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/users/alice/disable")
                    .header("authorization", "Bearer root-token")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert!(json["user"]["disabled_at"].is_i64());

        let resp = router
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/users/alice/enable")
                    .header("authorization", "Bearer root-token")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert!(json["user"]["disabled_at"].is_null());
    }

    async fn admin_call(
        router: &Router,
        method: &str,
        uri: &str,
        token: &str,
        body: Option<serde_json::Value>,
    ) -> (StatusCode, serde_json::Value) {
        let mut builder = Request::builder()
            .method(method)
            .uri(uri)
            .header("authorization", format!("Bearer {token}"));
        let body = match body {
            Some(json) => {
                builder = builder.header("content-type", "application/json");
                Body::from(serde_json::to_vec(&json).unwrap())
            }
            None => Body::empty(),
        };
        let resp = router
            .clone()
            .oneshot(builder.body(body).unwrap())
            .await
            .unwrap();
        let status = resp.status();
        let bytes = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json = serde_json::from_slice(&bytes).unwrap_or(serde_json::Value::Null);
        (status, json)
    }

    /// The operator's whole grant workflow over HTTP, as `ai-memory user grant`
    /// drives it.
    #[tokio::test]
    async fn grants_can_be_issued_changed_listed_and_revoked_by_root() {
        let (_tmp, router) = user_admin_test_router("root-token");
        let _ = post_create_human_user(
            &router,
            "root-token",
            serde_json::json!({"username": "alice"}),
        )
        .await;
        let (status, _) = admin_call(
            &router,
            "POST",
            "/admin/write-page",
            "root-token",
            Some(serde_json::json!({
                "workspace": "default",
                "project": "client-work",
                "path": "notes/seed.md",
                "body": "exists so the repository does",
            })),
        )
        .await;
        assert_eq!(status, StatusCode::OK);

        let target = |level: Option<&str>| {
            let mut body = serde_json::json!({
                "workspace": "default",
                "project": "client-work",
            });
            if let Some(level) = level {
                body["level"] = level.into();
            }
            Some(body)
        };

        // A level left unsaid is refused, not defaulted.
        let (status, _) = admin_call(
            &router,
            "POST",
            "/admin/users/alice/grant",
            "root-token",
            target(None),
        )
        .await;
        assert_eq!(status, StatusCode::BAD_REQUEST);
        let (status, _) = admin_call(
            &router,
            "POST",
            "/admin/users/alice/grant",
            "root-token",
            target(Some("owner")),
        )
        .await;
        assert_eq!(
            status,
            StatusCode::BAD_REQUEST,
            "unknown level must not be guessed at"
        );
        // There is no per-project administrator: administration is root's.
        let (status, _) = admin_call(
            &router,
            "POST",
            "/admin/users/alice/grant",
            "root-token",
            target(Some("admin")),
        )
        .await;
        assert_eq!(
            status,
            StatusCode::BAD_REQUEST,
            "admin is not a grant level"
        );

        let (status, json) = admin_call(
            &router,
            "POST",
            "/admin/users/alice/grant",
            "root-token",
            target(Some("write")),
        )
        .await;
        assert_eq!(status, StatusCode::OK);
        assert_eq!(json["changed"], true);
        assert!(json["previous"].is_null());

        let (_, json) = admin_call(
            &router,
            "POST",
            "/admin/users/alice/grant",
            "root-token",
            target(Some("write")),
        )
        .await;
        assert_eq!(
            json["changed"], false,
            "the same level again is not a change"
        );

        let (_, json) = admin_call(
            &router,
            "POST",
            "/admin/users/alice/grant",
            "root-token",
            target(Some("read")),
        )
        .await;
        assert_eq!(json["changed"], true);
        assert_eq!(json["previous"], "write");

        // A typo in the repository is a 404, and does not create it: asking
        // twice still finds nothing.
        for _ in 0..2 {
            let (status, _) = admin_call(
                &router,
                "POST",
                "/admin/users/alice/grant",
                "root-token",
                Some(serde_json::json!({
                    "workspace": "default",
                    "project": "client-wrok",
                    "level": "read",
                })),
            )
            .await;
            assert_eq!(status, StatusCode::NOT_FOUND);
        }

        let (status, json) =
            admin_call(&router, "GET", "/admin/projects/grants", "root-token", None).await;
        assert_eq!(status, StatusCode::OK);
        assert_eq!(
            json["grants"],
            serde_json::json!([{
                "username": "alice",
                "workspace": "default",
                "project": "client-work",
                "level": "read",
            }])
        );
        // The same grant seen from the user and from the project.
        let (_, by_user) = admin_call(
            &router,
            "GET",
            "/admin/users/alice/grants",
            "root-token",
            None,
        )
        .await;
        assert_eq!(by_user["grants"], json["grants"]);
        let (_, by_project) = admin_call(
            &router,
            "GET",
            "/admin/projects/grants?workspace=default&project=client-work",
            "root-token",
            None,
        )
        .await;
        assert_eq!(by_project["grants"], json["grants"]);
        let (status, _) = admin_call(
            &router,
            "GET",
            "/admin/projects/grants?workspace=default",
            "root-token",
            None,
        )
        .await;
        assert_eq!(status, StatusCode::BAD_REQUEST, "workspace without project");

        let (_, json) = admin_call(
            &router,
            "POST",
            "/admin/users/alice/revoke",
            "root-token",
            target(None),
        )
        .await;
        assert_eq!(json["revoked"], true);
        let (_, json) = admin_call(
            &router,
            "POST",
            "/admin/users/alice/revoke",
            "root-token",
            target(None),
        )
        .await;
        assert_eq!(json["revoked"], false, "revoking twice reports honestly");
    }

    async fn write_fixture_page(router: &Router, workspace: &str, project: &str, path: &str) {
        let (status, json) = admin_call(
            router,
            "POST",
            "/admin/write-page",
            "root-token",
            Some(serde_json::json!({
                "workspace": workspace,
                "project": project,
                "path": path,
                "body": format!("lives in {workspace}/{project}"),
            })),
        )
        .await;
        assert_eq!(status, StatusCode::OK, "{json}");
    }

    async fn grant_alice(router: &Router, workspace: &str, project: &str) {
        let (status, json) = admin_call(
            router,
            "POST",
            "/admin/users/alice/grant",
            "root-token",
            Some(serde_json::json!({
                "workspace": workspace,
                "project": project,
                "level": "write",
            })),
        )
        .await;
        assert_eq!(status, StatusCode::OK, "{json}");
    }

    async fn grants_in_force(router: &Router) -> serde_json::Value {
        let (_, json) =
            admin_call(router, "GET", "/admin/projects/grants", "root-token", None).await;
        json["grants"].clone()
    }

    /// A grant never outlives its project (#708): the destructive operations
    /// proceed exactly as they do without grants, and the grants go with what
    /// they granted — the design's CASCADE.
    #[tokio::test]
    async fn purging_a_project_takes_its_grants() {
        let (_tmp, router) = user_admin_test_router("root-token");
        let _ = post_create_human_user(
            &router,
            "root-token",
            serde_json::json!({"username": "alice"}),
        )
        .await;
        write_fixture_page(&router, "default", "client-work", "notes/a.md").await;
        grant_alice(&router, "default", "client-work").await;
        assert_eq!(grants_in_force(&router).await.as_array().unwrap().len(), 1);

        let (status, json) = admin_call(
            &router,
            "POST",
            "/admin/purge-project",
            "root-token",
            Some(serde_json::json!({
                "workspace": "default",
                "project": "client-work",
                "confirm": true,
            })),
        )
        .await;
        assert_eq!(status, StatusCode::OK, "{json}");
        assert_eq!(grants_in_force(&router).await, serde_json::json!([]));
    }

    /// A merging move copies the source into an existing destination and then
    /// purges the source: the source's grants go with it, and none appear on
    /// the destination — carrying them across would widen someone's access to
    /// the destination's other content.
    #[tokio::test]
    async fn a_merging_move_does_not_carry_grants_to_the_destination() {
        let (_tmp, router) = user_admin_test_router("root-token");
        let _ = post_create_human_user(
            &router,
            "root-token",
            serde_json::json!({"username": "alice"}),
        )
        .await;
        write_fixture_page(&router, "team-a", "shared", "notes/from-a.md").await;
        write_fixture_page(&router, "team-b", "shared", "notes/from-b.md").await;
        grant_alice(&router, "team-a", "shared").await;

        let (status, json) = admin_call(
            &router,
            "POST",
            "/admin/move-project",
            "root-token",
            Some(serde_json::json!({
                "from_workspace": "team-a",
                "project": "shared",
                "to_workspace": "team-b",
                "confirm": true, "allow_lossy_merge": true,
            })),
        )
        .await;
        assert_eq!(status, StatusCode::OK, "{json}");
        assert_eq!(grants_in_force(&router).await, serde_json::json!([]));
    }

    #[tokio::test]
    async fn deleting_a_workspace_takes_its_grants() {
        let (_tmp, router) = user_admin_test_router("root-token");
        let _ = post_create_human_user(
            &router,
            "root-token",
            serde_json::json!({"username": "alice"}),
        )
        .await;
        write_fixture_page(&router, "team-c", "api", "notes/x.md").await;
        grant_alice(&router, "team-c", "api").await;

        let (status, json) = admin_call(
            &router,
            "POST",
            "/admin/delete-workspace",
            "root-token",
            Some(serde_json::json!({"workspace": "team-c", "force": true})),
        )
        .await;
        assert_eq!(status, StatusCode::OK, "{json}");
        assert_eq!(grants_in_force(&router).await, serde_json::json!([]));
    }

    #[tokio::test]
    async fn only_root_may_touch_grants() {
        let (_tmp, router) = user_admin_test_router("root-token");
        // Any bearer that is not root authenticates as an ordinary user in
        // this harness. None of the grant routes may answer it: a user who
        // could grant would be a user who could grant themselves.
        for (method, uri) in [
            ("GET", "/admin/projects/grants"),
            ("GET", "/admin/users/alice/grants"),
            ("POST", "/admin/users/alice/grant"),
            ("POST", "/admin/users/alice/revoke"),
        ] {
            let body = (method == "POST").then(|| {
                serde_json::json!({
                    "workspace": "default",
                    "project": "client-work",
                    "level": "write",
                })
            });
            let (status, _) = admin_call(&router, method, uri, "not-root", body).await;
            assert_eq!(status, StatusCode::FORBIDDEN, "{method} {uri}");
        }
    }

    /// `POST /admin/projects/access` (#708): a mode is required and never
    /// guessed, the shared preferences scope cannot be restricted, a profile
    /// project's mode is fixed (a private one is never opened), an unknown
    /// project creates nothing, repeating a mode reports no change, and only
    /// root may call it.
    #[tokio::test]
    async fn project_access_sets_the_mode_and_refuses_what_it_must() {
        let (_tmp, router) = user_admin_test_router("root-token");
        write_fixture_page(&router, "default", "client-work", "notes/a.md").await;
        let call = |token: &'static str, body: serde_json::Value| {
            let router = router.clone();
            async move { admin_call(&router, "POST", "/admin/projects/access", token, Some(body)).await }
        };

        for body in [
            serde_json::json!({"workspace": "default", "project": "client-work"}),
            serde_json::json!({"workspace": "default", "project": "client-work", "mode": "members"}),
            serde_json::json!({"workspace": "default", "project": "_global", "mode": "restricted"}),
            serde_json::json!({"workspace": "default", "project": "_profile", "mode": "restricted"}),
            serde_json::json!({"workspace": "default", "project": "_profile.00000000000000000000000000000001", "mode": "open"}),
        ] {
            let (status, json) = call("root-token", body.clone()).await;
            assert_eq!(status, StatusCode::BAD_REQUEST, "{body} -> {json}");
        }
        let (status, _) = call(
            "root-token",
            serde_json::json!({"workspace": "default", "project": "nope", "mode": "restricted"}),
        )
        .await;
        assert_eq!(status, StatusCode::NOT_FOUND);

        let restrict = serde_json::json!({"workspace": "default", "project": "client-work", "mode": "restricted"});
        let (status, json) = call("root-token", restrict.clone()).await;
        assert_eq!(status, StatusCode::OK, "{json}");
        assert_eq!(json["mode"], "restricted");
        assert_eq!(json["previous"], "open");
        assert_eq!(json["changed"], true);
        let (_, json) = call("root-token", restrict.clone()).await;
        assert_eq!(json["changed"], false, "repeating a mode is not a change");

        let (status, _) = call("not-root", restrict).await;
        assert_eq!(status, StatusCode::FORBIDDEN);
    }

    #[tokio::test]
    async fn disable_unknown_user_returns_404() {
        let (_tmp, router) = user_admin_test_router("root-token");
        let resp = router
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/users/ghost/disable")
                    .header("authorization", "Bearer root-token")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::NOT_FOUND);
    }

    #[tokio::test]
    async fn rotate_api_credential_issues_a_distinct_secret() {
        let (_tmp, router) = user_admin_test_router("root-token");
        let _ = post_create_human_user(
            &router,
            "root-token",
            serde_json::json!({"username": "alice"}),
        )
        .await;
        let create_resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/api-credentials")
                    .header("authorization", "Bearer root-token")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "username": "alice",
                            "label": "laptop"
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(create_resp.status(), StatusCode::OK);
        let body = to_bytes(create_resp.into_body(), usize::MAX).await.unwrap();
        let created: serde_json::Value = serde_json::from_slice(&body).unwrap();
        let original_token = created["token"].as_str().unwrap().to_string();
        let id = created["credential"]["id"].as_str().unwrap();
        assert!(original_token.starts_with("aim_"));

        let resp = router
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri(format!("/admin/api-credentials/{id}/rotate"))
                    .header("authorization", "Bearer root-token")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        let new_token = json["token"].as_str().unwrap();
        assert!(new_token.starts_with("aim_"));
        assert_ne!(new_token, original_token, "rotate must change the secret");
    }

    #[tokio::test]
    async fn create_human_user_works_without_pepper_but_api_keys_return_503() {
        // Humans do not need a pepper. Native API keys still do.
        use ai_memory_core::ActorContext;
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        let router = admin_router(AdminState {
            ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),
            mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),
            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: ProviderHealth::default(),
            decay_params: DecayParams::default(),
            contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
            contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
            data_dir: tmp.path().to_path_buf(),
            db_path: store.db_path().to_path_buf(),
            bind: "127.0.0.1:49374".to_string(),
            home_dir: None,
            bootstrap_lock: Arc::new(tokio::sync::Mutex::new(())),
            token_pepper: None,
            active_project: ai_memory_core::ActiveProject::new(),
            scope_invalidator: None,
            trusted_proxy_identity: false,
        });
        // Inject Root so the human create reaches its handler; only native
        // API credentials require the pepper.
        let router = router.layer(axum::middleware::from_fn(
            |mut req: Request<Body>, next: axum::middleware::Next| async move {
                req.extensions_mut().insert(ai_memory_core::AuthLevel::Root);
                req.extensions_mut().insert(ActorContext::anonymous());
                next.run(req).await
            },
        ));

        let created = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/human-users")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({"username": "alice"})).unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(created.status(), StatusCode::OK);

        let resp = router
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/api-credentials")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "username": "alice",
                            "label": "cli"
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SERVICE_UNAVAILABLE);
        let _ = tmp;
    }

    #[tokio::test]
    async fn patch_demotion_of_last_recoverable_root_returns_409() {
        let (_tmp, router) = user_admin_test_router("root-token");
        let created = post_create_human_user(
            &router,
            "root-token",
            serde_json::json!({"username": "keeper", "role": "root"}),
        )
        .await;
        assert_eq!(created.status(), StatusCode::OK);
        let body = to_bytes(created.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(json["user"]["role"], "root");
        assert_eq!(json["user"]["has_password"].as_bool(), Some(true));

        let resp = patch_user(
            &router,
            "root-token",
            "keeper",
            serde_json::json!({"role": "user"}),
        )
        .await;
        assert_eq!(resp.status(), StatusCode::CONFLICT);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert!(
            json["error"]
                .as_str()
                .unwrap_or("")
                .contains("last recoverable root"),
            "409 body must surface the store InvalidState mapping; got {json:?}"
        );
    }

    #[tokio::test]
    async fn disable_of_last_recoverable_root_returns_409() {
        let (_tmp, router) = user_admin_test_router("root-token");
        let created = post_create_human_user(
            &router,
            "root-token",
            serde_json::json!({"username": "keeper", "role": "root"}),
        )
        .await;
        assert_eq!(created.status(), StatusCode::OK);

        let resp = post_disable_user(&router, "root-token", "keeper").await;
        assert_eq!(resp.status(), StatusCode::CONFLICT);
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert!(
            json["error"]
                .as_str()
                .unwrap_or("")
                .contains("last recoverable root"),
            "409 body must surface the store InvalidState mapping; got {json:?}"
        );
    }

    #[tokio::test]
    async fn concurrent_root_removals_leave_one_recoverable_root() {
        let (_tmp, router) = user_admin_test_router("root-token");
        for name in ["alice", "bob"] {
            let created = post_create_human_user(
                &router,
                "root-token",
                serde_json::json!({"username": name, "role": "root"}),
            )
            .await;
            assert_eq!(created.status(), StatusCode::OK, "setup {name}");
        }

        let (demote, disable) = tokio::join!(
            patch_user(
                &router,
                "root-token",
                "alice",
                serde_json::json!({"role": "user"}),
            ),
            post_disable_user(&router, "root-token", "bob"),
        );
        let statuses = [demote.status(), disable.status()];
        let ok = statuses.iter().filter(|s| **s == StatusCode::OK).count();
        assert!(
            ok <= 1,
            "at most one concurrent root-removal may succeed; got {statuses:?}"
        );
        assert!(
            statuses
                .iter()
                .all(|s| *s == StatusCode::OK || *s == StatusCode::CONFLICT),
            "root-removal must be 200 or 409; got {statuses:?}"
        );

        let listed = router
            .oneshot(
                Request::builder()
                    .uri("/admin/users")
                    .header("authorization", "Bearer root-token")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(listed.status(), StatusCode::OK);
        let body = to_bytes(listed.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        let recoverable = json["users"]
            .as_array()
            .unwrap()
            .iter()
            .filter(|u| {
                u["role"] == "root"
                    && u["disabled_at"].is_null()
                    && u["has_password"].as_bool() == Some(true)
            })
            .count();
        assert!(
            recoverable >= 1,
            "a recoverable root must remain after concurrent removals; got {json:?}"
        );
    }

    #[tokio::test]
    async fn native_api_token_for_root_role_user_cannot_manage_users() {
        let (_tmp, router) = user_admin_dual_auth_router("root-token");
        let created = post_create_human_user(
            &router,
            "root-token",
            serde_json::json!({"username": "boss", "role": "root"}),
        )
        .await;
        assert_eq!(created.status(), StatusCode::OK);
        let body = to_bytes(created.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(json["user"]["role"], "root");

        let issued = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/api-credentials")
                    .header("authorization", "Bearer root-token")
                    .header("content-type", "application/json")
                    .body(Body::from(
                        serde_json::to_vec(&serde_json::json!({
                            "username": "boss",
                            "label": "legacy-user-token"
                        }))
                        .unwrap(),
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(issued.status(), StatusCode::OK);
        let body = to_bytes(issued.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        let native_token = json["token"].as_str().unwrap();
        assert!(native_token.starts_with("aim_"));

        let as_native = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/admin/users")
                    .header("authorization", format!("Bearer {native_token}"))
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            as_native.status(),
            StatusCode::FORBIDDEN,
            "role=root must not elevate a looked-up native API credential"
        );

        let unknown = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/admin/users")
                    .header("authorization", "Bearer aim_not-a-stored-credential")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            unknown.status(),
            StatusCode::UNAUTHORIZED,
            "unknown bearer must 401 through real lookup, not a User stub"
        );

        let as_root = router
            .oneshot(
                Request::builder()
                    .uri("/admin/users")
                    .header("authorization", "Bearer root-token")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(as_root.status(), StatusCode::OK);
    }

    // ---------------------------------------------------------------------
    // delete-page
    // ---------------------------------------------------------------------

    /// Helper: POST /admin/delete-page and return (status, body json).
    async fn post_delete_page(
        router: &Router,
        ws: &str,
        project: &str,
        path: &str,
    ) -> (StatusCode, serde_json::Value) {
        let req_body = serde_json::json!({
            "workspace": ws,
            "project": project,
            "path": path,
        });
        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/delete-page")
                    .header("content-type", "application/json")
                    .body(Body::from(serde_json::to_vec(&req_body).unwrap()))
                    .unwrap(),
            )
            .await
            .unwrap();
        let status = resp.status();
        let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
        let json: serde_json::Value =
            serde_json::from_slice(&body).unwrap_or(serde_json::json!({}));
        (status, json)
    }

    #[tokio::test]
    async fn delete_page_removes_existing_page() {
        let (_tmp, router) = read_page_test_router();
        post_write_page(&router, "default", "audit", "notes/doomed.md", "bye body").await;

        // Confirm the page is reachable before delete.
        let resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/admin/read-page?workspace=default&project=audit&path=notes/doomed.md")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            resp.status(),
            StatusCode::OK,
            "setup precondition: page must exist before delete"
        );

        let (status, json) = post_delete_page(&router, "default", "audit", "notes/doomed.md").await;
        assert_eq!(status, StatusCode::OK);
        assert_eq!(json["path"], "notes/doomed.md");
        assert_eq!(json["deleted"], true);

        // Read-back must now 404.
        let resp = router
            .oneshot(
                Request::builder()
                    .uri("/admin/read-page?workspace=default&project=audit&path=notes/doomed.md")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            resp.status(),
            StatusCode::NOT_FOUND,
            "page must be gone after delete"
        );
    }

    /// A delete request whose `(workspace, project)` doesn't resolve to a
    /// real `(WorkspaceId, ProjectId)` must NOT report success. The shared
    /// `resolve_ws_proj` returns the unresolved-scope error; the handler
    /// surfaces it as a 4xx/5xx — never as `deleted: true`. This guards the
    /// Bug 5 regression where MCP `memory_delete_page` returned `true` for
    /// a scope it never touched.
    #[tokio::test]
    async fn delete_page_unknown_workspace_does_not_fake_success() {
        let (_tmp, router) = read_page_test_router();
        let (status, json) =
            post_delete_page(&router, "no-such-ws", "audit", "notes/whatever.md").await;
        assert_ne!(
            status,
            StatusCode::OK,
            "delete on unresolved scope must not return 200/deleted=true; got body {json:?}",
        );
        assert!(
            json.get("deleted").and_then(|v| v.as_bool()) != Some(true),
            "body must not claim deleted=true on unresolved scope; got {json:?}"
        );
    }

    /// `Wiki::delete_page` is idempotent for a path that doesn't exist
    /// inside an EXISTING (workspace, project) — the file is just not there
    /// to quarantine. The handler reports `deleted: true` (i.e. "the call
    /// succeeded") rather than 404, matching the documented MCP semantics.
    #[tokio::test]
    async fn delete_page_idempotent_for_missing_file_in_existing_scope() {
        let (_tmp, router) = read_page_test_router();
        // Seed the project so (workspace, project) resolves, but skip the
        // page we'll try to delete.
        post_write_page(&router, "default", "audit", "notes/keep.md", "keeper").await;

        let (status, json) =
            post_delete_page(&router, "default", "audit", "notes/never-existed.md").await;
        assert_eq!(status, StatusCode::OK);
        assert_eq!(json["deleted"], true);
    }

    #[tokio::test]
    async fn delete_page_traversal_rejected_with_422() {
        let (_tmp, router) = read_page_test_router();
        let (status, _) = post_delete_page(&router, "default", "audit", "../etc/passwd").await;
        assert_eq!(status, StatusCode::UNPROCESSABLE_ENTITY);
    }
}