heptagent-memory-tool-backend 0.1.0

// SPDX-License-Identifier: MIT
// Copyright (c) 2026 heptagent core team
// (Plan K-00 Phase 14 — heptagent-memory-tool-backend crate v0.1.0; 14-FIX-PACK OQ-FP-2 renamed)
//
// L5 cherry-pick gate (ADR-0015 Rule 3 RE-DERIVE mandate):
//   gh search code --repo ultraworkers/claw-code "memory_20250818" → 0 Rust hits
//   gh search code --repo ultraworkers/claw-code "MemoryDispatcher" → 0 Rust hits
//   gh search code --repo ultraworkers/claw-code "QuestRateLimiter" → 0 Rust hits
//   Conclusion: RE-DERIVE — Anthropic memory_20250818 protocol backend is novel;
//   no upstream Rust implementation exists. NP42 crates.io publish pattern.
//
// Protocol verified: WebFetch github.com/saribmah/llm-kit memory_20250818.rs
// 6 commands: view / create / str_replace / insert / delete / rename

//! `heptagent-memory-tool-backend` — Rust backend for the Anthropic `memory_20250818` tool-call protocol.
//!
//! First published Rust implementation of the Anthropic memory tool protocol.
//!
//! ## Architecture
//!
//! - [`MemoryCommand`] — 6-command enum deserialized from Worker tool-call JSON.
//! - [`MemoryBackend`] — FROZEN async trait (NP42); `RedbMemoryBackend` is the v0.1 impl.
//! - [`MemoryDispatcher`] — routes `MemoryCommand` to backend + enforces rate limit.
//! - [`QuestRateLimiter`] — D-C-03: 20 calls/quest hard cap (AtomicU32).
//!
//! ## Security
//!
//! - **T-14-00-01**: `MemoryCommand` uses `serde(tag = "command", rename_all = "snake_case")`
//!   strict deserialization — unknown command variants are rejected.
//! - **T-14-00-02**: All `#[instrument]` on dispatcher methods skip plaintext content fields
//!   per NP25 zero-knowledge invariant.
//! - **T-14-00-03**: `QuestRateLimiter` enforces 20 calls/quest cap.
//! - **T-14-00-05**: Path validation rejects `..` traversal + absolute paths.

pub mod error;
pub mod rate_limiter;

use std::sync::Arc;

use async_trait::async_trait;
use redb::ReadableTable as _;
use serde::{Deserialize, Serialize};
use tracing::instrument;

pub use error::MemoryError;
pub use rate_limiter::QuestRateLimiter;

// ── MemoryCommand ────────────────────────────────────────────────────────────

/// Anthropic `memory_20250818` protocol commands — 6-variant enum.
///
/// Deserialized from Worker tool-call JSON via `serde(tag = "command", rename_all = "snake_case")`.
/// Unknown commands → serde deserialization error (T-14-00-01 strict mode).
///
/// Spike scope: all 6 commands backed by redb string KV.
/// Production K-02: path prefix → Tier1Category routing + Megrez vault encryption.
#[derive(Debug, Deserialize)]
#[serde(tag = "command", rename_all = "snake_case")]
pub enum MemoryCommand {
    /// Read file content, optionally within a line range.
    View {
        path: String,
        /// Optional [start_line, end_line] (1-indexed, inclusive).
        view_range: Option<[u32; 2]>,
    },
    /// Create a new file with given content (fails if path already exists).
    Create { path: String, file_text: String },
    /// Replace `old_str` with `new_str` in existing file.
    StrReplace {
        path: String,
        old_str: String,
        new_str: String,
    },
    /// Insert `insert_text` after `insert_line` (1-indexed; 0 = prepend).
    Insert {
        path: String,
        insert_line: u32,
        insert_text: String,
    },
    /// Delete a file.
    Delete { path: String },
    /// Rename a file.
    Rename { old_path: String, new_path: String },
}

// ── MemoryResult ─────────────────────────────────────────────────────────────

/// Result returned to Worker after dispatching a `MemoryCommand`.
///
/// Mirrors Anthropic tool-result message shape: `content` + `is_error` flag.
#[derive(Debug, Serialize)]
pub struct MemoryResult {
    /// Text content (file content for View; status message for mutating ops).
    pub content: String,
    /// `true` if the operation failed; Worker should inspect `content` for reason.
    pub is_error: bool,
}

impl MemoryResult {
    fn ok(content: impl Into<String>) -> Self {
        Self {
            content: content.into(),
            is_error: false,
        }
    }

    fn err(msg: impl Into<String>) -> Self {
        Self {
            content: msg.into(),
            is_error: true,
        }
    }
}

// ── MemoryBackend trait ───────────────────────────────────────────────────────

/// **NP42 FROZEN async trait** — backend abstraction for memory_20250818 storage.
///
/// Multi-impl surface:
/// - Production v0.1: [`RedbMemoryBackend`] (local KV store)
/// - Production K-02+: Megrez-vault-backed encrypted impl
/// - Test: mock impl via `#[cfg(test)]` closures
///
/// **Pattern P1 object-safety guard** — see bottom of file.
#[async_trait]
pub trait MemoryBackend: Send + Sync {
    async fn view(&self, path: &str, range: Option<[u32; 2]>) -> Result<String, MemoryError>;
    async fn create(&self, path: &str, file_text: &str) -> Result<(), MemoryError>;
    async fn str_replace(&self, path: &str, old: &str, new_text: &str) -> Result<(), MemoryError>;
    async fn insert(&self, path: &str, line: u32, text: &str) -> Result<(), MemoryError>;
    async fn delete(&self, path: &str) -> Result<(), MemoryError>;
    async fn rename(&self, old_path: &str, new_path: &str) -> Result<(), MemoryError>;
}

// ── Path validation ───────────────────────────────────────────────────────────

/// Validate memory path for security (T-14-00-05).
///
/// Rejects: `..` traversal, absolute paths (`/` or `\` prefix).
/// Spike: accepts any tier-prefixed or unprefixed path.
/// Production K-02: enforces Tier1Category routing (user/ feedback/ project/ reference/).
fn validate_path(path: &str) -> Result<(), MemoryError> {
    if path.contains("..") || path.starts_with('/') || path.starts_with('\\') {
        return Err(MemoryError::PathInvalid(path.to_string()));
    }
    if path.is_empty() {
        return Err(MemoryError::PathInvalid("<empty>".to_string()));
    }
    Ok(())
}

// ── RedbMemoryBackend ─────────────────────────────────────────────────────────

const MEMORY_FILES_TABLE: redb::TableDefinition<&str, &str> =
    redb::TableDefinition::new("memory_files");

/// redb-backed implementation of [`MemoryBackend`].
///
/// Spike scope: all 6 commands backed by a single redb KV table
/// `memory_files: key=path_str → value=file_content_str`.
///
/// Production K-02: path prefix → Tier1Category routing + age-encrypted Megrez vault backend.
pub struct RedbMemoryBackend {
    db: Arc<redb::Database>,
}

impl RedbMemoryBackend {
    /// Open or create a redb database at `path`.
    pub fn new(db_path: &std::path::Path) -> Result<Self, MemoryError> {
        let db = redb::Database::create(db_path).map_err(|e| MemoryError::Redb(e.to_string()))?;
        Ok(Self { db: Arc::new(db) })
    }
}

#[async_trait]
impl MemoryBackend for RedbMemoryBackend {
    #[instrument(skip(self), fields(path))]
    async fn view(&self, path: &str, range: Option<[u32; 2]>) -> Result<String, MemoryError> {
        validate_path(path)?;
        let read_txn = self.db.begin_read()?;
        let table = read_txn.open_table(MEMORY_FILES_TABLE).map_err(|e| {
            if matches!(e, redb::TableError::TableDoesNotExist(_)) {
                MemoryError::PathNotFound(path.to_string())
            } else {
                MemoryError::Redb(e.to_string())
            }
        })?;
        match table.get(path)? {
            None => Err(MemoryError::PathNotFound(path.to_string())),
            Some(guard) => {
                let content: &str = guard.value();
                if let Some([start, end]) = range {
                    // 1-indexed, inclusive.
                    // 14-FIX-PACK P1-8: bounds-check before slice to prevent panic on
                    // malformed Worker output (start > end OR end > lines.len()).
                    let lines: Vec<&str> = content.lines().collect();
                    let start_idx = (start as usize).saturating_sub(1);
                    let end_idx = end as usize;
                    let len = lines.len();
                    // Validate: start_idx must be < len AND start_idx <= end_idx clamped at len.
                    if start_idx >= len || start_idx > end_idx.min(len) {
                        return Err(MemoryError::RangeInvalid {
                            start: start as usize,
                            end: end as usize,
                            len,
                        });
                    }
                    // end beyond content length is NOT an error — clamp silently.
                    let end_clamped = end_idx.min(len);
                    Ok(lines[start_idx..end_clamped].join("\n"))
                } else {
                    Ok(content.to_string())
                }
            }
        }
    }

    #[instrument(skip(self, file_text), fields(path))]
    async fn create(&self, path: &str, file_text: &str) -> Result<(), MemoryError> {
        validate_path(path)?;
        // 14-FIX-PACK P0-2: existence check BEFORE write (memory_20250818 spec requires
        // create() to fail on existing path — prevents silent overwrite).
        {
            let read_txn = self.db.begin_read()?;
            let table = match read_txn.open_table(MEMORY_FILES_TABLE) {
                Ok(t) => t,
                Err(redb::TableError::TableDoesNotExist(_)) => {
                    // Table not yet created — path definitely doesn't exist; skip check.
                    drop(read_txn);
                    let write_txn = self.db.begin_write()?;
                    {
                        let mut table = write_txn.open_table(MEMORY_FILES_TABLE)?;
                        table.insert(path, file_text)?;
                    }
                    write_txn.commit()?;
                    return Ok(());
                }
                Err(e) => return Err(MemoryError::from(e)),
            };
            if table.get(path)?.is_some() {
                return Err(MemoryError::PathExists {
                    path: path.to_string(),
                });
            }
        }
        let write_txn = self.db.begin_write()?;
        {
            let mut table = write_txn.open_table(MEMORY_FILES_TABLE)?;
            table.insert(path, file_text)?;
        }
        write_txn.commit()?;
        Ok(())
    }

    #[instrument(skip(self, old_str, new_text), fields(path))]
    async fn str_replace(
        &self,
        path: &str,
        old_str: &str,
        new_text: &str,
    ) -> Result<(), MemoryError> {
        validate_path(path)?;
        let write_txn = self.db.begin_write()?;
        {
            let mut table = write_txn.open_table(MEMORY_FILES_TABLE)?;
            let existing = table
                .get(path)?
                .ok_or_else(|| MemoryError::PathNotFound(path.to_string()))?;
            let content = existing.value().to_string();
            drop(existing);
            if !content.contains(old_str) {
                return Err(MemoryError::OldStrNotFound {
                    path: path.to_string(),
                });
            }
            let updated = content.replacen(old_str, new_text, 1);
            table.insert(path, updated.as_str())?;
        }
        write_txn.commit()?;
        Ok(())
    }

    #[instrument(skip(self, text), fields(path, insert_line))]
    async fn insert(&self, path: &str, insert_line: u32, text: &str) -> Result<(), MemoryError> {
        validate_path(path)?;
        let write_txn = self.db.begin_write()?;
        {
            let mut table = write_txn.open_table(MEMORY_FILES_TABLE)?;
            let existing = table
                .get(path)?
                .ok_or_else(|| MemoryError::PathNotFound(path.to_string()))?;
            let content = existing.value().to_string();
            drop(existing);
            let mut lines: Vec<String> = content.lines().map(str::to_string).collect();
            let idx = insert_line as usize;
            if idx > lines.len() {
                return Err(MemoryError::InsertOutOfRange {
                    path: path.to_string(),
                    line: insert_line,
                });
            }
            lines.insert(idx, text.to_string());
            let updated = lines.join("\n");
            table.insert(path, updated.as_str())?;
        }
        write_txn.commit()?;
        Ok(())
    }

    #[instrument(skip(self), fields(path))]
    async fn delete(&self, path: &str) -> Result<(), MemoryError> {
        validate_path(path)?;
        let write_txn = self.db.begin_write()?;
        {
            let mut table = write_txn.open_table(MEMORY_FILES_TABLE)?;
            table.remove(path)?;
        }
        write_txn.commit()?;
        Ok(())
    }

    #[instrument(skip(self), fields(old_path, new_path))]
    async fn rename(&self, old_path: &str, new_path: &str) -> Result<(), MemoryError> {
        validate_path(old_path)?;
        validate_path(new_path)?;
        let write_txn = self.db.begin_write()?;
        {
            let mut table = write_txn.open_table(MEMORY_FILES_TABLE)?;
            let existing = table
                .get(old_path)?
                .ok_or_else(|| MemoryError::PathNotFound(old_path.to_string()))?;
            let content = existing.value().to_string();
            drop(existing);
            table.remove(old_path)?;
            table.insert(new_path, content.as_str())?;
        }
        write_txn.commit()?;
        Ok(())
    }
}

// ── MemoryDispatcher ──────────────────────────────────────────────────────────

/// Routes [`MemoryCommand`] to backend + enforces rate limit.
///
/// **NP42** — `MemoryDispatcher<B: MemoryBackend>` is the v0.1 production type.
/// Spike: instantiate with `RedbMemoryBackend` + `QuestRateLimiter::new(20)`.
pub struct MemoryDispatcher<B: MemoryBackend> {
    backend: Arc<B>,
    rate_limiter: QuestRateLimiter,
}

impl<B: MemoryBackend> MemoryDispatcher<B> {
    /// Create a new dispatcher.
    pub fn new(backend: B, rate_limiter: QuestRateLimiter) -> Self {
        Self {
            backend: Arc::new(backend),
            rate_limiter,
        }
    }

    /// Dispatch a `MemoryCommand` to the backend.
    ///
    /// Rate-limits per D-C-03 (20 calls/quest).
    /// Returns `MemoryResult { is_error: true }` on rate-limit OR backend error.
    pub async fn dispatch(&self, cmd: MemoryCommand) -> MemoryResult {
        if let Err(e) = self.rate_limiter.try_consume() {
            return MemoryResult::err(e.to_string());
        }
        match self.dispatch_inner(cmd).await {
            Ok(result) => result,
            Err(e) => MemoryResult::err(e.to_string()),
        }
    }

    async fn dispatch_inner(&self, cmd: MemoryCommand) -> Result<MemoryResult, MemoryError> {
        match cmd {
            MemoryCommand::View { path, view_range } => {
                let content = self.backend.view(&path, view_range).await?;
                Ok(MemoryResult::ok(content))
            }
            MemoryCommand::Create { path, file_text } => {
                self.backend.create(&path, &file_text).await?;
                Ok(MemoryResult::ok(format!("Created: {path}")))
            }
            MemoryCommand::StrReplace {
                path,
                old_str,
                new_str,
            } => {
                self.backend.str_replace(&path, &old_str, &new_str).await?;
                Ok(MemoryResult::ok(format!("Updated: {path}")))
            }
            MemoryCommand::Insert {
                path,
                insert_line,
                insert_text,
            } => {
                self.backend
                    .insert(&path, insert_line, &insert_text)
                    .await?;
                Ok(MemoryResult::ok(format!(
                    "Inserted at line {insert_line} in {path}"
                )))
            }
            MemoryCommand::Delete { path } => {
                self.backend.delete(&path).await?;
                Ok(MemoryResult::ok(format!("Deleted: {path}")))
            }
            MemoryCommand::Rename { old_path, new_path } => {
                self.backend.rename(&old_path, &new_path).await?;
                Ok(MemoryResult::ok(format!(
                    "Renamed: {old_path} → {new_path}"
                )))
            }
        }
    }

    /// Reset rate limiter at quest boundary.
    pub fn reset_for_new_quest(&self) {
        self.rate_limiter.reset_for_new_quest();
    }
}

// ── Pattern P1 object-safety guard ───────────────────────────────────────────
// Verify MemoryBackend is dyn-safe (required for MockMemoryBackend + TestDouble patterns).
// Compile-time check only — zero runtime cost.
const _: fn() = || {
    fn _assert_object_safe(_b: &dyn MemoryBackend) {}
};

// ── Unit tests ────────────────────────────────────────────────────────────────

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

    #[test]
    fn memory_command_deserializes_view() {
        let json = r#"{"command":"view","path":"user/foo.md","view_range":null}"#;
        let cmd: MemoryCommand = serde_json::from_str(json).unwrap();
        assert!(
            matches!(cmd, MemoryCommand::View { path, view_range: None } if path == "user/foo.md")
        );
    }

    #[test]
    fn memory_command_deserializes_create() {
        let json = r#"{"command":"create","path":"project/bar.md","file_text":"content here"}"#;
        let cmd: MemoryCommand = serde_json::from_str(json).unwrap();
        assert!(
            matches!(cmd, MemoryCommand::Create { path, file_text } if path == "project/bar.md" && file_text == "content here")
        );
    }

    #[test]
    fn memory_command_deserializes_str_replace() {
        let json = r#"{"command":"str_replace","path":"p.md","old_str":"old","new_str":"new"}"#;
        let cmd: MemoryCommand = serde_json::from_str(json).unwrap();
        assert!(matches!(cmd, MemoryCommand::StrReplace { .. }));
    }

    #[test]
    fn path_validation_rejects_traversal() {
        assert!(validate_path("../etc/passwd").is_err());
        assert!(validate_path("/absolute/path").is_err());
        assert!(validate_path("\\windows\\path").is_err());
        assert!(validate_path("").is_err());
    }

    #[test]
    fn path_validation_accepts_valid() {
        assert!(validate_path("user/decisions.md").is_ok());
        assert!(validate_path("project/arch.md").is_ok());
        assert!(validate_path("some-file.md").is_ok());
    }

    /// T-FP-02 — create() returns PathExists when path already exists.
    ///
    /// 14-FIX-PACK P0-2: memory_20250818 spec violation fix — create() must reject
    /// existing paths rather than silently overwriting. This test verifies the guard.
    #[tokio::test]
    async fn t_fp_02_create_path_exists_returns_error() {
        let dir = tempfile::tempdir().unwrap();
        let db_path = dir.path().join("test.redb");
        let backend = RedbMemoryBackend::new(&db_path).unwrap();

        // First create should succeed.
        backend
            .create("user/test.md", "initial content")
            .await
            .unwrap();

        // Second create on the same path MUST return PathExists.
        let result = backend.create("user/test.md", "overwrite attempt").await;
        assert!(
            matches!(result, Err(MemoryError::PathExists { ref path }) if path == "user/test.md"),
            "expected PathExists, got: {result:?}"
        );

        // Original content must be preserved (no overwrite occurred).
        let content = backend.view("user/test.md", None).await.unwrap();
        assert_eq!(
            content, "initial content",
            "original content must not be overwritten"
        );
    }

    /// T-FP-03 — LICENSE file is present alongside Cargo.toml (P0-3 fix verification).
    ///
    /// This is a compile-time structural check: the test calls std::fs to verify the
    /// LICENSE file exists in the crate directory. Fails if LICENSE is missing from the
    /// published crate (crates.io publish would be missing the LICENSE file).
    #[test]
    fn t_fp_03_license_file_present() {
        let crate_dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
        let license_path = crate_dir.join("LICENSE");
        assert!(
            license_path.exists(),
            "P0-3: LICENSE file missing at {license_path:?}. cargo publish requires LICENSE for MIT crates."
        );
    }

    /// T-FP-25a — `view` returns `RangeInvalid` when start > end (1-indexed).
    ///
    /// 14-FIX-PACK P1-8: Anthropic backend view_range bounds check.
    /// Worker-supplied `view_range=[10, 2]` (start > end) must return RangeInvalid,
    /// NOT panic with `slice index starts at X but ends at Y`.
    #[tokio::test]
    async fn t_fp_25a_view_returns_range_invalid_for_start_greater_than_end() {
        let dir = tempfile::tempdir().unwrap();
        let db_path = dir.path().join("test.redb");
        let backend = RedbMemoryBackend::new(&db_path).unwrap();

        // Create a 5-line file.
        backend
            .create("user/range_test.md", "line1\nline2\nline3\nline4\nline5")
            .await
            .unwrap();

        // start=10, end=2 — start > end → must return RangeInvalid, NOT panic.
        let result = backend.view("user/range_test.md", Some([10, 2])).await;
        assert!(
            matches!(result, Err(MemoryError::RangeInvalid { .. })),
            "P1-8: view([10,2]) on 5-line content must return RangeInvalid, got: {result:?}"
        );
    }

    /// T-FP-25b — `view` with end beyond content length is clamped (not an error).
    ///
    /// 14-FIX-PACK P1-8: When end > lines.len(), the view is silently clamped to
    /// lines.len() per the implementation directive (NOT an error for out-of-bounds end).
    /// Only start > end AND start >= len are errors.
    #[tokio::test]
    async fn t_fp_25b_view_with_end_beyond_content_clamps_silently() {
        let dir = tempfile::tempdir().unwrap();
        let db_path = dir.path().join("test.redb");
        let backend = RedbMemoryBackend::new(&db_path).unwrap();

        // Create a 3-line file.
        backend
            .create("user/clamp_test.md", "alpha\nbeta\ngamma")
            .await
            .unwrap();

        // start=1, end=9999 — end beyond content → clamp to 3 lines, return all content.
        let result = backend.view("user/clamp_test.md", Some([1, 9999])).await;
        assert!(
            result.is_ok(),
            "view([1,9999]) on 3-line content should clamp, not error: {result:?}"
        );
        let content = result.unwrap();
        assert_eq!(content, "alpha\nbeta\ngamma");
    }
}