ucxl/

lib.rs

//! UCXL core data structures and utilities.
//!
//! This module provides the fundamental types used throughout the CHORUS
//! system for addressing resources (UCXL addresses), handling temporal axes,
//! and storing lightweight metadata. The implementation is deliberately
//! lightweight and in‑memory to keep the core fast and dependency‑free.

pub mod watcher;

use std::collections::HashMap;
use std::fmt;
use std::str::FromStr;

/// Represents the temporal axis in a UCXL address.
///
/// **What**: An enumeration of the three supported temporal positions –
/// present, past, and future – each represented by a symbolic string in the
/// address format.
///
/// **How**: The enum derives `Debug`, `PartialEq`, `Eq`, `Clone`, and `Copy`
/// for ergonomic usage. Conversions to and from strings are provided via the
/// `FromStr` and `fmt::Display` implementations.
///
/// **Why**: Temporal axes enable UCXL to refer to data at different points in
/// time (e.g. versioned resources). The simple three‑state model matches the
/// CHURUS architectural decision to keep addressing lightweight while still
/// supporting historical and speculative queries.
#[derive(Debug, PartialEq, Eq, Clone, Copy)]
pub enum TemporalAxis {
    /// Present ("#") – the current version of a resource.
    Present,
    /// Past ("~~") – a historical snapshot of a resource.
    Past,
    /// Future ("^^") – a speculative or planned version of a resource.
    Future,
}

impl FromStr for TemporalAxis {
    type Err = String;
    /// Parses a temporal axis token from its textual representation.
    ///
    /// **What**: Accepts "#", "~~" or "^^" and maps them to the corresponding
    /// enum variant.
    ///
    /// **How**: A simple `match` statement is used; an error string is
    /// returned for any unrecognised token.
    ///
    /// **Why**: Centralises validation of temporal markers used throughout the
    /// address parsing logic, ensuring consistency.
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "#" => Ok(TemporalAxis::Present),
            "~~" => Ok(TemporalAxis::Past),
            "^^" => Ok(TemporalAxis::Future),
            _ => Err(format!("Invalid temporal axis: {}", s)),
        }
    }
}

impl fmt::Display for TemporalAxis {
    /// Formats the temporal axis back to its string token.
    ///
    /// **What**: Returns "#", "~~" or "^^" depending on the variant.
    ///
    /// **How**: Matches on `self` and writes the corresponding string to the
    /// formatter.
    ///
    /// **Why**: Required for serialising a `UCXLAddress` back to its textual
    /// representation.
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let s = match self {
            TemporalAxis::Present => "#",
            TemporalAxis::Past => "~~",
            TemporalAxis::Future => "^^",
        };
        write!(f, "{}", s)
    }
}

/// Represents a parsed UCXL address.
///
/// **What**: Holds the components extracted from a UCXL URI – the agent, an
/// optional role, the project identifier, task name, temporal axis, and the
/// resource path within the project.
///
/// **How**: The struct is constructed via the `FromStr` implementation which
/// validates the scheme, splits the address into its constituent parts and
/// populates the fields. The `Display` implementation performs the inverse
/// operation.
///
/// **Why**: UCXL addresses are the primary routing mechanism inside CHORUS.
/// Encapsulating them in a dedicated type provides type‑safety and makes it
/// easy to work with address components in the rest of the codebase.
#[derive(Debug, PartialEq, Eq, Clone)]
pub struct UCXLAddress {
    /// The identifier of the agent (e.g., a user or system component).
    pub agent: String,
    /// Optional role associated with the agent (e.g., "admin").
    pub role: Option<String>,
    /// The project namespace this address belongs to.
    pub project: String,
    /// The specific task within the project.
    pub task: String,
    /// Temporal axis indicating present, past or future.
    pub temporal: TemporalAxis,
    /// Path to the resource relative to the project root.
    pub path: String,
}

impl FromStr for UCXLAddress {
    type Err = String;
    /// Parses a full UCXL address string into a `UCXLAddress` value.
    ///
    /// **What**: Validates the scheme (`ucxl://`), extracts the agent, optional
    /// role, project, task, temporal axis and the trailing resource path.
    ///
    /// **How**: The implementation performs a series of `split` operations,
    /// handling optional components and converting the temporal token via
    /// `TemporalAxis::from_str`. Errors are surfaced as descriptive strings.
    ///
    /// **Why**: Centralises address parsing logic, ensuring that all parts of
    /// the system interpret UCXL URIs consistently.
    fn from_str(address: &str) -> Result<Self, Self::Err> {
        // Ensure the scheme is correct
        let scheme_split: Vec<&str> = address.splitn(2, "://").collect();
        if scheme_split.len() != 2 || scheme_split[0] != "ucxl" {
            return Err("Address must start with 'ucxl://'".into());
        }
        let remainder = scheme_split[1];
        // Split at the first '@' to separate agent/role from project/task
        let parts: Vec<&str> = remainder.splitn(2, '@').collect();
        if parts.len() != 2 {
            return Err("Missing '@' separating agent and project".into());
        }
        // Agent and optional role
        let agent_part = parts[0];
        let mut agent_iter = agent_part.splitn(2, ':');
        let agent = agent_iter.next().unwrap().to_string();
        let role = agent_iter.next().map(|s| s.to_string());
        // Project and task
        let project_task_part = parts[1];
        // Find the first '/' that starts the temporal segment and path
        let slash_idx = project_task_part
            .find('/')
            .ok_or("Missing '/' before temporal segment and path")?;
        let (proj_task, after_slash) = project_task_part.split_at(slash_idx);
        let mut proj_task_iter = proj_task.splitn(2, ':');
        let project = proj_task_iter.next().ok_or("Missing project")?.to_string();
        let task = proj_task_iter.next().ok_or("Missing task")?.to_string();
        // after_slash starts with '/', remove it
        let after = &after_slash[1..];
        // Temporal segment is up to the next '/' if present
        let temporal_end = after
            .find('/')
            .ok_or("Missing '/' after temporal segment")?;
        let temporal_str = &after[..temporal_end];
        let temporal = TemporalAxis::from_str(temporal_str)?;
        // The rest is the resource path
        let path = after[temporal_end + 1..].to_string();
        Ok(UCXLAddress {
            agent,
            role,
            project,
            task,
            temporal,
            path,
        })
    }
}

impl fmt::Display for UCXLAddress {
    /// Serialises the address back to its canonical string form.
    ///
    /// **What**: Constructs a `ucxl://` URI including optional role and path.
    ///
    /// **How**: Conditionally inserts the role component, then formats the
    /// project, task, temporal token and optional path using standard `write!`
    /// semantics.
    ///
    /// **Why**: Needed when emitting addresses (e.g., logging events or
    /// generating links) so that external tools can consume them.
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let role_part = if let Some(r) = &self.role {
            format!(":{}", r)
        } else {
            "".to_string()
        };
        write!(
            f,
            "ucxl://{}{}@{}:{}/{}{}",
            self.agent,
            role_part,
            self.project,
            self.task,
            self.temporal,
            if self.path.is_empty() {
                "".to_string()
            } else {
                format!("/{}", self.path)
            }
        )
    }
}

/// Trait defining a simple key‑value metadata store.
///
/// **What**: Provides read, write and removal operations for associating a
/// string of metadata with a file‑system path.
///
/// **How**: The trait abstracts over concrete storage implementations –
/// currently an in‑memory `HashMap` – allowing callers to depend on the trait
/// rather than a specific type.
///
/// **Why**: CHORUS needs a lightweight way to attach auxiliary information to
/// files without persisting to a database; the trait makes it easy to swap in a
/// persistent backend later if required.
pub trait MetadataStore {
    /// Retrieves the metadata for `path` if it exists.
    fn get(&self, path: &str) -> Option<&String>;
    /// Stores `metadata` for `path`, overwriting any existing value.
    fn set(&mut self, path: &str, metadata: String);
    /// Removes the metadata entry for `path`, returning the old value if any.
    fn remove(&mut self, path: &str) -> Option<String> {
        None
    }
}

/// In‑memory implementation of `MetadataStore` backed by a `HashMap`.
///
/// **What**: Holds metadata in a hash map where the key is the file path.
///
/// **How**: Provides a `new` constructor and implements the `MetadataStore`
/// trait methods by delegating to the underlying map.
///
/// **Why**: Offers a zero‑cost, dependency‑free store suitable for unit tests
/// and simple scenarios. It can be replaced with a persistent store without
/// changing callers.
pub struct InMemoryMetadataStore {
    map: HashMap<String, String>,
}

impl InMemoryMetadataStore {
    /// Creates a fresh, empty `InMemoryMetadataStore`.
    ///
    /// **What**: Returns a struct with an empty internal map.
    ///
    /// **How**: Calls `HashMap::new`.
    ///
    /// **Why**: Convenience constructor for callers.
    pub fn new() -> Self {
        InMemoryMetadataStore {
            map: HashMap::new(),
        }
    }
}

impl MetadataStore for InMemoryMetadataStore {
    fn get(&self, path: &str) -> Option<&String> {
        self.map.get(path)
    }
    fn set(&mut self, path: &str, metadata: String) {
        self.map.insert(path.to_string(), metadata);
    }
    fn remove(&mut self, path: &str) -> Option<String> {
        self.map.remove(path)
    }
}

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

    #[test]
    fn test_temporal_from_str() {
        assert_eq!(TemporalAxis::from_str("#").unwrap(), TemporalAxis::Present);
        assert_eq!(TemporalAxis::from_str("~~").unwrap(), TemporalAxis::Past);
        assert_eq!(TemporalAxis::from_str("^^").unwrap(), TemporalAxis::Future);
    }

    #[test]
    fn test_ucxl_address_parsing() {
        let addr_str = "ucxl://alice:admin@myproj:task1/#/docs/readme.md";
        let addr = UCXLAddress::from_str(addr_str).unwrap();
        assert_eq!(addr.agent, "alice");
        assert_eq!(addr.role, Some("admin".to_string()));
        assert_eq!(addr.project, "myproj");
        assert_eq!(addr.task, "task1");
        assert_eq!(addr.temporal, TemporalAxis::Present);
        assert_eq!(addr.path, "docs/readme.md");
        assert_eq!(addr.to_string(), addr_str);
    }

    #[test]
    fn test_metadata_store() {
        let mut store = InMemoryMetadataStore::new();
        store.set("/foo.txt", "meta".into());
        assert_eq!(store.get("/foo.txt"), Some(&"meta".to_string()));
        store.remove("/foo.txt");
        assert!(store.get("/foo.txt").is_none());
    }
}