Docs: Comprehensive inline rustdoc and architectural summary PDF

UCXL/src/lib.rs

@@ -1,4 +1,9 @@
-// UCXL Core Data Structures
+//! 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;
 
@@ -7,18 +12,41 @@ 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 ("#")
+    /// Present ("#") – the current version of a resource.
     Present,
-    /// Past ("~~")
+    /// Past ("~~") – a historical snapshot of a resource.
     Past,
-    /// Future ("^^")
+    /// 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),
@@ -30,6 +58,15 @@ impl FromStr for TemporalAxis {
 }
 
 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 => "#",
@@ -41,18 +78,48 @@ impl fmt::Display for TemporalAxis {
 }
 
 /// 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();
@@ -102,6 +169,16 @@ impl FromStr for UCXLAddress {
 }
 
 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)
@@ -125,21 +202,51 @@ impl fmt::Display for UCXLAddress {
     }
 }
 
-/// Simple in‑memory metadata store mapping a file path to a metadata string.
+/// 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
     }
 }
 
-/// A concrete in‑memory implementation using a HashMap.
+/// 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(),

UCXL/src/watcher.rs

@@ -1,20 +1,63 @@
+//! UCXL filesystem watcher.
+//!
+//! This module provides a thin wrapper around the `notify` crate to watch a
+//! directory (or "project") for filesystem events. When a change is detected,
+//! the watcher attempts to construct a corresponding `UCXLAddress` using a
+//! simple heuristic and logs the event. This is primarily used by CHORUS for
+//! reactive workflows such as automatically updating metadata when files are
+//! added, modified or removed.
+
 use notify::{Config, RecommendedWatcher, RecursiveMode, Watcher};
 use std::path::Path;
 use std::sync::mpsc::channel;
-use crate::{UCXLAddress, TemporalAxis};
+use crate::UCXLAddress;
 use std::str::FromStr;
 
+/// Represents a watcher rooted at a specific base path.
+///
+/// **What**: Holds the absolute path that the watcher monitors.
+///
+/// **How**: The path is stored as a `PathBuf`. The watcher is created via the
+/// `new` constructor which accepts any type that can be referenced as a `Path`.
+/// The underlying `notify::RecommendedWatcher` is configured with the default
+/// `Config` and set to watch recursively.
+///
+/// **Why**: Encapsulating the watcher logic in a dedicated struct makes it easy
+/// to instantiate multiple independent watchers and keeps the public API tidy.
 pub struct UCXLWatcher {
     base_path: std::path::PathBuf,
 }
 
 impl UCXLWatcher {
+    /// Creates a new `UCXLWatcher` for the given path.
+    ///
+    /// **What**: Accepts any generic `AsRef<Path>` so callers can pass a `&str`,
+    /// `Path`, or `PathBuf`.
+    ///
+    /// **How**: The provided path is converted to a `PathBuf` and stored.
+    ///
+    /// **Why**: Convenience constructor used throughout CHORUS when a watcher is
+    /// needed for a project directory.
     pub fn new<P: AsRef<Path>>(path: P) -> Self {
         Self {
             base_path: path.as_ref().to_path_buf(),
         }
     }
 
+    /// Starts the watch loop, blocking indefinitely while handling events.
+    ///
+    /// **What**: Sets up a channel, creates a `RecommendedWatcher`, and begins
+    /// watching the `base_path` recursively. For each incoming event, it
+    /// attempts to map the filesystem path to a UCXL address and prints a log.
+    ///
+    /// **How**: Uses the `notify` crate's event API. The heuristic address
+    /// format is `ucxl://system:watcher@local:filesystem/#/<relative_path>`.
+    /// It parses this string with `UCXLAddress::from_str` and logs the result.
+    /// Errors from parsing are ignored (they simply aren't printed).
+    ///
+    /// **Why**: Provides a simple, observable bridge between raw filesystem
+    /// changes and the UCXL addressing scheme, allowing other components to react
+    /// to changes using a uniform identifier.
     pub fn watch_loop(&self) -> Result<(), Box<dyn std::error::Error>> {
         let (tx, rx) = channel();
 
@@ -29,8 +72,11 @@ impl UCXLWatcher {
                     for path in event.paths {
                         if let Some(rel_path) = path.strip_prefix(&self.base_path).ok() {
                             let rel_str = rel_path.to_string_lossy();
-                            // Attempt a heuristic address mapping: ucxl://system:watcher@local:filesystem/#/path
-                            let addr_str = format!("ucxl://system:watcher@local:filesystem/#/{}", rel_str);
+                            // Heuristic address mapping: ucxl://system:watcher@local:filesystem/#/path
+                            let addr_str = format!(
+                                "ucxl://system:watcher@local:filesystem/#/{}",
+                                rel_str
+                            );
                             if let Ok(addr) = UCXLAddress::from_str(&addr_str) {
                                 println!("[UCXL EVENT] {:?} -> {}", event.kind, addr);
                             }