taskchampion-rb 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cafd2930e70aef0ac31c03c98e3d806cd1fba49408ce69b4bcb5d41074465c3f
-  data.tar.gz: 23b8948a759f8cc7b28e2cb68d65d40750943bd05bf127a87f5e25bf80116900
+  metadata.gz: d661bc07cbe2c900550df0973e28fbc8ca3ed34fb8f607e91bdff8824239a6dc
+  data.tar.gz: e4c5b2908fcac0ec63dcaa1c9e179a6a0b17701cb9c04c884738b4977f86ed64
 SHA512:
-  metadata.gz: 2ff558c7674c2ff686e08ec9e220baa966edf438353e42832a566771cbcb2348c329d34fa27937b7bc9b71c0fdd7721f6e3086a675a5baa4e54f2e4e102600a5
-  data.tar.gz: 34dfcc7ea08bc2f90b846d3a19b1526731a0142d1cc6d09a867923bd6620be3abc13602eab12f8022c85dfc10b3f97502c62419808db3b942808489efbd51488
+  metadata.gz: 7aa047cb7dc2adb780e8c2616f726126df2e07bc53e8a357d507d4742ef099a438ed126a7f5849bb43e86136b14dc8044a6038fe7104e94c9a633db6d61101d1
+  data.tar.gz: 5fb6d41847c431265d85114505b385e36d05c9e5dc7006c92c3c1e29a89adb015a2486f7620b613b28a8132bb1b30f3e6e4d777ee1ba81e623e17aaae7cc441b

data/README.md

@@ -8,6 +8,7 @@ This gem supports Ruby 3.2 and later. We follow Ruby's end-of-life (EOL) schedul
 
 - **Ruby 3.2**: Supported (EOL: March 2026)
 - **Ruby 3.3**: Supported (Current stable)
+- **Ruby 3.4**: Supported
 - **Ruby 3.0-3.1**: Not supported (reached EOL)
 
 ## Installation

data/docs/ANNOTATION_IMPLEMENTATION.md

@@ -0,0 +1,642 @@
+# Annotation Management Implementation Plan
+
+## Overview
+
+This document outlines the implementation plan for adding `remove_annotation` and `update_annotation` methods to the TaskChampion Ruby bindings, enabling full annotation lifecycle management.
+
+## Current State
+
+### Existing Functionality
+
+**Annotation Class** (`ext/taskchampion/src/annotation.rs`)
+- Wraps TaskChampion Rust library's `Annotation` type
+- Properties:
+  - `entry`: DateTime timestamp when annotation was created
+  - `description`: Text content of the annotation
+- Methods: `new`, `entry`, `description`, `to_s`, `inspect`, `eql?`, `hash`
+
+**Task Methods** (`ext/taskchampion/src/task.rs`)
+- `task.annotations` - Returns array of Annotation objects (read-only)
+- `task.add_annotation(description, operations)` - Adds new annotation with auto-generated timestamp
+
+### Limitations
+- No way to remove annotations once added
+- No way to edit/update existing annotations
+- Annotations are effectively append-only
+
+## Design Decisions
+
+### Decision 1: API for `remove_annotation`
+**Chosen: Option A - Pass full Annotation object**
+
+```ruby
+annotation = task.annotations.first
+task.remove_annotation(annotation, operations)
+```
+
+**Rationale:**
+- Most Ruby-idiomatic approach
+- User doesn't need to extract timestamp manually
+- Mirrors standard Ruby collection methods (e.g., `Array#delete`)
+- Consistent with Ruby's object-oriented design
+
+**Alternatives Considered:**
+- Option B: Pass timestamp only - More explicit but less intuitive
+- Option C: Support both - Added complexity without significant benefit
+
+### Decision 2: Method Name for Editing
+**Chosen: Option A - `update_annotation`**
+
+```ruby
+task.update_annotation(annotation, "Updated description", operations)
+```
+
+**Rationale:**
+- Matches Rails/Ruby conventions (ActiveRecord uses `update`)
+- Clearly indicates modification intent
+- Common pattern in Ruby APIs
+
+**Alternatives Considered:**
+- `edit_annotation` - More conversational but less conventional
+- `replace_annotation` - More accurate to implementation but unfamiliar
+- No convenience method - Too low-level for common use case
+
+### Decision 3: Timestamp Preservation
+**Chosen: Option A - Preserve original timestamp**
+
+When updating an annotation, the original `entry` timestamp is preserved.
+
+```ruby
+annotation = task.annotations.first  # entry: 2025-01-15 10:00:00
+task.update_annotation(annotation, "Updated text", operations)
+# Result: entry still shows 2025-01-15 10:00:00
+```
+
+**Rationale:**
+- Maintains chronological history (shows when annotation was originally created)
+- Audit trail remains intact
+- Aligns with TaskWarrior philosophy of immutable timestamps
+- Users can see historical context even after editing
+
+**Alternatives Considered:**
+- Update to current timestamp - Loses original creation time
+- User choice via parameter - Added API complexity
+
+### Decision 4: Implementation Location
+**Chosen: Option A - Pure Ruby wrapper in `lib/taskchampion.rb`**
+
+```ruby
+class Task
+  def update_annotation(annotation, new_description, operations)
+    remove_annotation(annotation, operations)
+    add_annotation(new_description, operations)
+  end
+end
+```
+
+**Rationale:**
+- Easier to implement and maintain
+- Transparent implementation (users can see it's remove + add)
+- No Rust compilation needed for changes
+- Adequate performance for this use case
+
+**Alternatives Considered:**
+- Rust implementation - More atomic but adds complexity
+
+### Decision 5: Error Handling
+**Chosen: Option A - Silent success (match Rust behavior)**
+
+Attempting to remove a non-existent annotation succeeds silently without error.
+
+```ruby
+task.remove_annotation(non_existent_annotation, operations)
+# No error - operation succeeds even if annotation doesn't exist
+```
+
+**Rationale:**
+- Matches underlying Rust library behavior
+- Idempotent (safe to call multiple times)
+- Simple implementation
+- Consistent with underlying system design
+
+**Alternatives Considered:**
+- Raise ValidationError - More defensive but inconsistent with Rust layer
+- Return boolean - Less Ruby-idiomatic
+
+## Implementation Details
+
+### 1. Rust Extension Changes
+
+**File:** `ext/taskchampion/src/task.rs`
+
+Add `remove_annotation` method:
+
+```rust
+fn remove_annotation(&self, annotation: &Annotation, operations: &crate::operations::Operations) -> Result<(), Error> {
+    let mut task = self.0.get_mut()?;
+    let entry_timestamp = annotation.0.entry;
+
+    operations.with_inner_mut(|ops| {
+        task.remove_annotation(entry_timestamp, ops)
+    })?;
+    Ok(())
+}
+```
+
+Register in `init()` function:
+
+```rust
+class.define_method("remove_annotation", method!(Task::remove_annotation, 2))?;
+```
+
+### 2. Ruby Wrapper Changes
+
+**File:** `lib/taskchampion.rb`
+
+Add to Task class:
+
+```ruby
+class Task
+  # Update an existing annotation's description while preserving its timestamp
+  #
+  # @param annotation [Taskchampion::Annotation] The annotation to update
+  # @param new_description [String] The new description text
+  # @param operations [Taskchampion::Operations] Operations collection
+  # @return [void]
+  #
+  # @example
+  #   annotation = task.annotations.first
+  #   task.update_annotation(annotation, "Updated note", operations)
+  #   replica.commit_operations(operations)
+  #
+  def update_annotation(annotation, new_description, operations)
+    # Remove the old annotation
+    remove_annotation(annotation, operations)
+
+    # Add new annotation with preserved timestamp
+    # Note: add_annotation creates a new timestamp, so we need to use the lower-level API
+    # This preserves the original entry time
+    entry_time = annotation.entry
+    new_ann = Taskchampion::Annotation.new(entry_time, new_description)
+
+    # We need to expose add_annotation that accepts an Annotation object
+    # For now, document that timestamp preservation requires the annotation
+    # to be removed and re-added with the same timestamp
+    remove_annotation(annotation, operations)
+
+    # Create new annotation with same timestamp
+    # This will require modifying add_annotation to accept either:
+    # 1. A description string (current behavior - auto timestamp)
+    # 2. An Annotation object (new behavior - preserve timestamp)
+  end
+end
+```
+
+**Note:** This reveals we need to modify `add_annotation` to support passing an Annotation object directly, or add a separate lower-level method.
+
+### 3. Revised Implementation Approach
+
+Given the need to preserve timestamps, we have two options:
+
+#### Option A: Modify `add_annotation` to accept Annotation objects
+
+```rust
+// In task.rs, modify add_annotation signature
+fn add_annotation(&self, arg: Value, operations: &Operations) -> Result<(), Error> {
+    let mut task = self.0.get_mut()?;
+
+    // Check if arg is an Annotation object or a String
+    if let Ok(annotation) = <&Annotation>::try_convert(arg) {
+        // User passed an Annotation object - use its timestamp
+        operations.with_inner_mut(|ops| {
+            task.add_annotation(annotation.0.clone(), ops)
+        })?;
+    } else if let Ok(description) = String::try_convert(arg) {
+        // User passed a string - create new annotation with current time
+        // ... existing implementation ...
+    } else {
+        return Err(Error::new(
+            crate::error::validation_error(),
+            "add_annotation expects an Annotation object or description string"
+        ));
+    }
+    Ok(())
+}
+```
+
+#### Option B: Add separate `add_annotation_with_timestamp` method
+
+```rust
+fn add_annotation_with_timestamp(
+    &self,
+    timestamp: Value,
+    description: String,
+    operations: &Operations
+) -> Result<(), Error> {
+    let mut task = self.0.get_mut()?;
+    let entry = ruby_to_datetime(timestamp)?;
+
+    let annotation = taskchampion::Annotation {
+        entry,
+        description
+    };
+
+    operations.with_inner_mut(|ops| {
+        task.add_annotation(annotation, ops)
+    })?;
+    Ok(())
+}
+```
+
+Then Ruby wrapper:
+
+```ruby
+def update_annotation(annotation, new_description, operations)
+  remove_annotation(annotation, operations)
+  add_annotation_with_timestamp(annotation.entry, new_description, operations)
+end
+```
+
+**Recommendation:** Option B is cleaner and maintains backward compatibility.
+
+### 4. Testing Strategy
+
+**File:** `test/test_task.rb`
+
+```ruby
+def test_remove_annotation
+  replica = Taskchampion::Replica.new_in_memory
+  operations = Taskchampion::Operations.new
+
+  uuid = SecureRandom.uuid
+  task = replica.create_task(uuid, operations)
+  task.set_description("Test task", operations)
+
+  # Add annotations
+  task.add_annotation("First note", operations)
+  task.add_annotation("Second note", operations)
+  replica.commit_operations(operations)
+
+  # Verify both exist
+  retrieved = replica.task(uuid)
+  assert_equal 2, retrieved.annotations.length
+
+  # Remove first annotation
+  ops2 = Taskchampion::Operations.new
+  annotation_to_remove = retrieved.annotations.first
+  retrieved.remove_annotation(annotation_to_remove, ops2)
+  replica.commit_operations(ops2)
+
+  # Verify only one remains
+  final = replica.task(uuid)
+  assert_equal 1, final.annotations.length
+  assert_equal "Second note", final.annotations.first.description
+end
+
+def test_remove_annotation_nonexistent
+  replica = Taskchampion::Replica.new_in_memory
+  operations = Taskchampion::Operations.new
+
+  uuid = SecureRandom.uuid
+  task = replica.create_task(uuid, operations)
+  task.set_description("Test task", operations)
+  task.add_annotation("Note", operations)
+  replica.commit_operations(operations)
+
+  # Create annotation with different timestamp
+  fake_annotation = Taskchampion::Annotation.new(
+    DateTime.now + 1,
+    "Doesn't exist"
+  )
+
+  # Should not raise error
+  ops2 = Taskchampion::Operations.new
+  retrieved = replica.task(uuid)
+  assert_nothing_raised do
+    retrieved.remove_annotation(fake_annotation, ops2)
+  end
+  replica.commit_operations(ops2)
+
+  # Original annotation should still exist
+  final = replica.task(uuid)
+  assert_equal 1, final.annotations.length
+end
+
+def test_update_annotation
+  replica = Taskchampion::Replica.new_in_memory
+  operations = Taskchampion::Operations.new
+
+  uuid = SecureRandom.uuid
+  task = replica.create_task(uuid, operations)
+  task.set_description("Test task", operations)
+  task.add_annotation("Original note", operations)
+  replica.commit_operations(operations)
+
+  # Get annotation and note its timestamp
+  retrieved = replica.task(uuid)
+  annotation = retrieved.annotations.first
+  original_timestamp = annotation.entry
+
+  # Update annotation
+  ops2 = Taskchampion::Operations.new
+  retrieved.update_annotation(annotation, "Updated note", ops2)
+  replica.commit_operations(ops2)
+
+  # Verify description changed but timestamp preserved
+  final = replica.task(uuid)
+  assert_equal 1, final.annotations.length
+  updated = final.annotations.first
+  assert_equal "Updated note", updated.description
+
+  # Timestamp should be preserved (within 1 second tolerance)
+  time_diff = (updated.entry.to_time - original_timestamp.to_time).abs
+  assert time_diff < 1, "Timestamp should be preserved"
+end
+
+def test_update_annotation_empty_description
+  replica = Taskchampion::Replica.new_in_memory
+  operations = Taskchampion::Operations.new
+
+  uuid = SecureRandom.uuid
+  task = replica.create_task(uuid, operations)
+  task.set_description("Test task", operations)
+  task.add_annotation("Note", operations)
+  replica.commit_operations(operations)
+
+  retrieved = replica.task(uuid)
+  annotation = retrieved.annotations.first
+
+  # Should raise validation error for empty description
+  ops2 = Taskchampion::Operations.new
+  assert_raises Taskchampion::ValidationError do
+    retrieved.update_annotation(annotation, "", ops2)
+  end
+
+  assert_raises Taskchampion::ValidationError do
+    retrieved.update_annotation(annotation, "   ", ops2)
+  end
+end
+```
+
+**File:** `test/integration/test_task_lifecycle.rb`
+
+```ruby
+def test_annotation_removal_workflow
+  # Create task with multiple annotations
+  uuid = SecureRandom.uuid
+  task = @replica.create_task(uuid, @operations)
+  task.set_description("Task with annotations", @operations)
+
+  task.add_annotation("First annotation", @operations)
+  task.add_annotation("Second annotation", @operations)
+  task.add_annotation("Third annotation", @operations)
+  @replica.commit_operations(@operations)
+
+  # Remove middle annotation
+  retrieved = @replica.task(uuid)
+  annotations = retrieved.annotations.sort_by(&:entry)
+  middle_annotation = annotations[1]
+
+  ops2 = Taskchampion::Operations.new
+  retrieved.remove_annotation(middle_annotation, ops2)
+  @replica.commit_operations(ops2)
+
+  # Verify correct annotation was removed
+  final = @replica.task(uuid)
+  assert_equal 2, final.annotations.length
+  remaining_descriptions = final.annotations.map(&:description)
+  assert_includes remaining_descriptions, "First annotation"
+  assert_includes remaining_descriptions, "Third annotation"
+  refute_includes remaining_descriptions, "Second annotation"
+end
+
+def test_annotation_update_workflow
+  # Create task with annotation
+  uuid = SecureRandom.uuid
+  task = @replica.create_task(uuid, @operations)
+  task.set_description("Task to update", @operations)
+  task.add_annotation("Original text", @operations)
+  @replica.commit_operations(@operations)
+
+  # Update annotation multiple times
+  retrieved = @replica.task(uuid)
+  annotation = retrieved.annotations.first
+  original_entry = annotation.entry
+
+  ops2 = Taskchampion::Operations.new
+  retrieved.update_annotation(annotation, "First update", ops2)
+  @replica.commit_operations(ops2)
+
+  retrieved2 = @replica.task(uuid)
+  annotation2 = retrieved2.annotations.first
+  assert_equal "First update", annotation2.description
+
+  ops3 = Taskchampion::Operations.new
+  retrieved2.update_annotation(annotation2, "Second update", ops3)
+  @replica.commit_operations(ops3)
+
+  # Verify final state
+  final = @replica.task(uuid)
+  assert_equal 1, final.annotations.length
+  final_annotation = final.annotations.first
+  assert_equal "Second update", final_annotation.description
+
+  # Verify timestamp preserved through multiple updates
+  time_diff = (final_annotation.entry.to_time - original_entry.to_time).abs
+  assert time_diff < 1, "Original timestamp should be preserved"
+end
+```
+
+### 5. Documentation Updates
+
+**File:** `docs/API_REFERENCE.md`
+
+Add to Annotation Management section:
+
+```markdown
+#### Annotation Management
+
+```ruby
+# Add annotation
+task.add_annotation("Added note", operations)
+
+# Remove annotation
+annotation = task.annotations.first
+task.remove_annotation(annotation, operations)
+
+# Update annotation (preserves original timestamp)
+annotation = task.annotations.find { |a| a.description.include?("old text") }
+task.update_annotation(annotation, "New text", operations)
+
+# Commit changes
+replica.commit_operations(operations)
+```
+
+**Method Reference:**
+
+##### `task.remove_annotation(annotation, operations)`
+
+Removes an annotation from the task. Identified by the annotation's entry timestamp.
+
+- **Parameters:**
+  - `annotation` (Taskchampion::Annotation) - The annotation to remove
+  - `operations` (Taskchampion::Operations) - Operations collection
+- **Returns:** `nil`
+- **Raises:** None (silently succeeds if annotation doesn't exist)
+- **Example:**
+  ```ruby
+  annotation = task.annotations.first
+  task.remove_annotation(annotation, operations)
+  replica.commit_operations(operations)
+  ```
+
+##### `task.update_annotation(annotation, new_description, operations)`
+
+Updates an annotation's description while preserving its original timestamp.
+
+- **Parameters:**
+  - `annotation` (Taskchampion::Annotation) - The annotation to update
+  - `new_description` (String) - The new description text
+  - `operations` (Taskchampion::Operations) - Operations collection
+- **Returns:** `nil`
+- **Raises:**
+  - `Taskchampion::ValidationError` - If new_description is empty or whitespace-only
+- **Example:**
+  ```ruby
+  annotation = task.annotations.first
+  task.update_annotation(annotation, "Updated note", operations)
+  replica.commit_operations(operations)
+  ```
+- **Note:** This is a convenience method that removes the old annotation and adds a new one with the same timestamp, preserving the chronological history.
+```
+
+### 6. Example Code Updates
+
+**File:** `examples/basic_usage.rb`
+
+Add section after annotation display (around line 110):
+
+```ruby
+  # 5b. REMOVING AND UPDATING ANNOTATIONS
+  puts "\n5b. Removing and updating annotations"
+
+  # Get a task with annotations
+  task_with_ann = replica.task(uuid1)
+  if task_with_ann && !task_with_ann.annotations.empty?
+    puts "Original annotations: #{task_with_ann.annotations.length}"
+    task_with_ann.annotations.each do |ann|
+      puts "  - [#{ann.entry.strftime('%H:%M:%S')}] #{ann.description}"
+    end
+
+    # Update first annotation
+    operations_ann = Taskchampion::Operations.new
+    first_ann = task_with_ann.annotations.first
+    original_time = first_ann.entry
+
+    puts "\nUpdating first annotation..."
+    task_with_ann.update_annotation(first_ann, "Updated: Started learning TaskChampion", operations_ann)
+    replica.commit_operations(operations_ann)
+
+    # Verify update
+    task_updated = replica.task(uuid1)
+    updated_ann = task_updated.annotations.first
+    puts "Updated annotation: #{updated_ann.description}"
+    puts "Timestamp preserved: #{updated_ann.entry == original_time}"
+
+    # Add another annotation then remove it
+    operations_ann2 = Taskchampion::Operations.new
+    task_updated.add_annotation("Temporary note", operations_ann2)
+    replica.commit_operations(operations_ann2)
+
+    task_temp = replica.task(uuid1)
+    puts "\nAnnotations after adding temporary: #{task_temp.annotations.length}"
+
+    # Remove the temporary annotation
+    operations_ann3 = Taskchampion::Operations.new
+    temp_ann = task_temp.annotations.find { |a| a.description == "Temporary note" }
+    task_temp.remove_annotation(temp_ann, operations_ann3) if temp_ann
+    replica.commit_operations(operations_ann3)
+
+    task_final = replica.task(uuid1)
+    puts "Annotations after removal: #{task_final.annotations.length}"
+  end
+```
+
+## Implementation Checklist
+
+### Phase 1: Core `remove_annotation` Implementation
+- [ ] Add `remove_annotation` Rust method in `ext/taskchampion/src/task.rs`
+- [ ] Register method in `init()` function
+- [ ] Add `add_annotation_with_timestamp` Rust method for timestamp preservation
+- [ ] Register `add_annotation_with_timestamp` in `init()` function
+- [ ] Run `bundle exec rake compile` to build extension
+- [ ] Add unit tests in `test/test_task.rb`
+- [ ] Run tests: `bundle exec rake test TEST=test/test_task.rb`
+
+### Phase 2: Ruby `update_annotation` Wrapper
+- [ ] Add `update_annotation` method to Task class in `lib/taskchampion.rb`
+- [ ] Add comprehensive unit tests for update functionality
+- [ ] Add integration tests in `test/integration/test_task_lifecycle.rb`
+- [ ] Run full test suite: `bundle exec rake test`
+
+### Phase 3: Documentation & Examples
+- [ ] Update `docs/API_REFERENCE.md` with new methods
+- [ ] Add usage examples to `examples/basic_usage.rb`
+- [ ] Run example to verify: `ruby examples/basic_usage.rb`
+- [ ] Update CHANGELOG.md with new features
+
+### Phase 4: Code Quality
+- [ ] Run RuboCop: `bundle exec rake rubocop`
+- [ ] Fix any linting issues
+- [ ] Review error messages for clarity
+- [ ] Ensure consistent code style
+
+## Potential Future Enhancements
+
+### 1. Batch Operations
+Add methods for bulk annotation management:
+
+```ruby
+task.remove_annotations(annotations_array, operations)
+task.update_annotations(annotation_updates_hash, operations)
+```
+
+### 2. Annotation Filtering
+Add helper methods for finding annotations:
+
+```ruby
+task.find_annotation { |a| a.description.include?("text") }
+task.annotations_since(datetime)
+task.annotations_matching(pattern)
+```
+
+### 3. Annotation History
+Track annotation changes through operations log:
+
+```ruby
+task.annotation_history  # Returns timeline of all annotation changes
+```
+
+## Estimated Implementation Time
+
+- **Phase 1 (Rust methods):** 1-2 hours
+- **Phase 2 (Ruby wrapper & tests):** 1-2 hours
+- **Phase 3 (Documentation):** 30-60 minutes
+- **Phase 4 (Polish):** 30 minutes
+
+**Total:** 3-5 hours
+
+## Notes & Considerations
+
+1. **Thread Safety:** All methods maintain thread-bound safety through existing ThreadBound wrapper
+2. **Backward Compatibility:** All changes are additive - no breaking changes to existing API
+3. **Performance:** Ruby wrapper approach adds minimal overhead; acceptable for typical use cases
+4. **Synchronization:** All changes tracked through Operations system for replica sync
+5. **Validation:** Leverages existing validation in `add_annotation` for description validation
+
+## References
+
+- TaskChampion Rust library: `/home/tcase/Sites/reference/taskchampion`
+- Existing annotation implementation: `ext/taskchampion/src/annotation.rs`
+- Task implementation: `ext/taskchampion/src/task.rs`
+- Current tests: `test/test_task.rb`, `test/integration/test_task_lifecycle.rb`

data/docs/API_REFERENCE.md

@@ -142,8 +142,15 @@ task.add_tag(Taskchampion::Tag.new("work"), operations)
 task.remove_tag(Taskchampion::Tag.new("work"), operations)
 
 # Annotation management
-annotation = Taskchampion::Annotation.new(Time.now, "Added note")
-task.add_annotation(annotation, operations)
+task.add_annotation("Added note", operations)
+
+# Remove annotation
+annotation = task.annotations.first
+task.remove_annotation(annotation, operations)
+
+# Update annotation (preserves original timestamp)
+annotation = task.annotations.first
+task.update_annotation(annotation, "Updated text", operations)
 
 # UDA management
 task.set_uda("namespace", "key", "value", operations)

data/docs/date_conversion_analysis.md

@@ -0,0 +1,113 @@
+# Date Format Conversion in `task.set_due`
+
+## Overview
+
+When `task.set_due` is invoked in the TaskChampion Ruby gem, there **is** a format conversion from various Ruby date/time formats to a Unix timestamp for storage.
+
+## Conversion Flow
+
+The conversion follows this path: **Ruby date/time → UTC DateTime → Unix timestamp (stored as string)**
+
+### 1. Ruby Input Processing
+**Location**: `ext/taskchampion/src/task.rs:258-264`
+
+The `set_due` method accepts a Ruby `Value` which can be:
+- `nil` (to clear the due date)
+- A Ruby `Time` object
+- A Ruby `DateTime` object
+- A String in ISO 8601 format (e.g., "2023-01-01T12:00:00Z")
+- A String in the format "%Y-%m-%d %H:%M:%S %z"
+
+```rust
+fn set_due(&self, due: Value, operations: &crate::operations::Operations) -> Result<(), Error> {
+    let mut task = self.0.get_mut()?;
+    let due_datetime = ruby_to_option(due, ruby_to_datetime)?;
+    operations.with_inner_mut(|ops| {
+        task.set_due(due_datetime, ops)
+    })?;
+    Ok(())
+}
+```
+
+### 2. Conversion to Rust DateTime
+**Location**: `ext/taskchampion/src/util.rs:33-77`
+
+The `ruby_to_datetime` function converts the Ruby value to a Rust `DateTime<Utc>`:
+
+- **For `Time` objects**: Uses `strftime("%Y-%m-%dT%H:%M:%S%z")` to get ISO format, then parses it
+- **For `DateTime` objects**: Calls the `iso8601()` method, then parses the result
+- **For Strings**: Attempts to parse as RFC3339 first, then falls back to "%Y-%m-%d %H:%M:%S %z" format
+- **All dates are converted to UTC timezone**
+
+```rust
+pub fn ruby_to_datetime(value: Value) -> Result<DateTime<Utc>, Error> {
+    // String parsing
+    if let Ok(s) = RString::try_convert(value) {
+        let s = unsafe { s.as_str()? };
+        DateTime::parse_from_rfc3339(s)
+            .map(|dt| dt.with_timezone(&Utc))
+            .or_else(|_| DateTime::parse_from_str(s, "%Y-%m-%d %H:%M:%S %z")
+                .map(|dt| dt.with_timezone(&Utc)))
+            // ... error handling
+    } else {
+        // Ruby Time/DateTime object handling
+        let class_name = unsafe { value.class().name() };
+        let iso_string = if class_name == "Time" {
+            value.funcall::<_, (&str,), String>("strftime", ("%Y-%m-%dT%H:%M:%S%z",))?
+        } else {
+            value.funcall::<_, (), String>("iso8601", ())?
+        };
+        // Parse the ISO string...
+    }
+}
+```
+
+### 3. Storage as Unix Timestamp
+**Location**: `/home/tcase/Sites/reference/taskchampion/src/task/task.rs`
+
+The underlying TaskChampion library stores the date as a Unix timestamp:
+
+```rust
+pub fn set_due(&mut self, due: Option<Timestamp>, ops: &mut Operations) -> Result<()> {
+    self.set_timestamp(Prop::Due.as_ref(), due, ops)
+}
+
+pub fn set_timestamp(
+    &mut self,
+    property: &str,
+    value: Option<Timestamp>,
+    ops: &mut Operations,
+) -> Result<()> {
+    self.set_value(property, value.map(|v| v.timestamp().to_string()), ops)
+}
+```
+
+Where `Timestamp` is defined as:
+```rust
+pub(crate) type Timestamp = DateTime<Utc>;
+```
+
+The `.timestamp()` method converts the `DateTime<Utc>` to Unix timestamp (seconds since epoch), which is then converted to a string for storage (e.g., "1704067200").
+
+### 4. Retrieval Process
+**Location**: `ext/taskchampion/src/task.rs`
+
+When retrieving the due date, it's converted back from Unix timestamp to a Ruby DateTime object:
+
+```rust
+fn due(&self) -> Result<Value, Error> {
+    let task = self.0.get()?;
+    option_to_ruby(task.get_due(), datetime_to_ruby)
+}
+```
+
+## Summary
+
+The `task.set_due` method performs comprehensive date format conversion:
+
+1. **Input**: Accepts various Ruby date/time formats and strings
+2. **Normalization**: Converts all inputs to UTC `DateTime<Utc>`
+3. **Storage**: Stores as Unix timestamp string in the underlying TaskChampion database
+4. **Retrieval**: Converts back to Ruby DateTime objects when accessed
+
+This ensures consistent date handling across different input formats while maintaining precision and timezone normalization.

data/examples/basic_usage.rb

@@ -171,6 +171,61 @@ begin
     puts "Task completed using set_status() method and committed"
   end
 
+  # 6b. ANNOTATION MANAGEMENT
+  puts "\n6b. Managing annotations (add, update, remove)"
+
+  # Get a task with annotations
+  task_with_ann = replica.task(uuid1)
+  if task_with_ann && !task_with_ann.annotations.empty?
+    puts "Task '#{task_with_ann.description}' has #{task_with_ann.annotations.length} annotation(s)"
+
+    # Display current annotations
+    puts "Current annotations:"
+    task_with_ann.annotations.each do |ann|
+      puts "  - [#{ann.entry.strftime('%H:%M:%S')}] #{ann.description}"
+    end
+
+    # Update the first annotation (preserves timestamp)
+    operations_ann = Taskchampion::Operations.new
+    first_ann = task_with_ann.annotations.first
+    original_time = first_ann.entry
+
+    puts "\nUpdating first annotation..."
+    task_with_ann.update_annotation(first_ann, "Updated: Started and completed learning TaskChampion", operations_ann)
+    replica.commit_operations(operations_ann)
+
+    # Verify update
+    task_updated = replica.task(uuid1)
+    updated_ann = task_updated.annotations.first
+    puts "Updated annotation: #{updated_ann.description}"
+    puts "Timestamp preserved: #{(updated_ann.entry.to_time - original_time.to_time).abs < 1}"
+
+    # Add a temporary annotation
+    operations_ann2 = Taskchampion::Operations.new
+    task_updated.add_annotation("Temporary progress note", operations_ann2)
+    replica.commit_operations(operations_ann2)
+
+    task_temp = replica.task(uuid1)
+    puts "\nAnnotations after adding temporary note: #{task_temp.annotations.length}"
+    task_temp.annotations.each do |ann|
+      puts "  - #{ann.description}"
+    end
+
+    # Remove the temporary annotation
+    operations_ann3 = Taskchampion::Operations.new
+    temp_ann = task_temp.annotations.find { |a| a.description.include?("Temporary") }
+    if temp_ann
+      task_temp.remove_annotation(temp_ann, operations_ann3)
+      replica.commit_operations(operations_ann3)
+
+      task_final = replica.task(uuid1)
+      puts "\nAnnotations after removal: #{task_final.annotations.length}"
+      task_final.annotations.each do |ann|
+        puts "  - #{ann.description}"
+      end
+    end
+  end
+
   # 7. WORKING WITH WORKING SET
   puts "\n7. Working with Working Set"
 

data/examples/undo_demo.rb

@@ -0,0 +1,104 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/taskchampion"
+
+# Create a replica for this demo
+replica = Taskchampion::Replica.new_in_memory
+
+puts "=== TaskChampion Undo/History Demo ==="
+
+# Create first task with undo point
+puts "\n1. Creating first task..."
+ops1 = Taskchampion::Operations.new
+ops1.push(Taskchampion::Operation.undo_point)
+task1 = replica.create_task("550e8400-e29b-41d4-a716-446655440000", ops1)
+task1.set_description("First task", ops1)
+replica.commit_operations(ops1)
+
+# Create second task with undo point
+puts "2. Creating second task..."
+ops2 = Taskchampion::Operations.new
+ops2.push(Taskchampion::Operation.undo_point)
+task2 = replica.create_task("550e8400-e29b-41d4-a716-446655440001", ops2)
+task2.set_description("Second task", ops2)
+task2.set_value("project", "home", ops2)
+replica.commit_operations(ops2)
+
+# Update task2's description to show old_value -> new_value
+puts "\n3. Updating second task's description..."
+ops3 = Taskchampion::Operations.new
+task2.set_description("Updated second task", ops3)
+replica.commit_operations(ops3)
+
+# Show current tasks
+puts "\n4. Current tasks:"
+replica.all_tasks.each do |uuid, task|
+  puts "  - #{task.description} (#{uuid})"
+end
+
+# Show task history for task2
+puts "\n5. History for second task:"
+task2_ops = replica.task_operations(task2.uuid)
+puts "  Operations count: #{task2_ops.length}"
+task2_ops.to_a.each_with_index do |op, i|
+  puts "  #{i + 1}. #{op.operation_type}"
+  if op.operation_type == :update
+    old_val = op.old_value.nil? ? "(none)" : op.old_value
+    new_val = op.value.nil? ? "(none)" : op.value
+    puts "    Details: #{op.property} changed from #{old_val} to #{new_val} at #{op.timestamp}"
+  end
+end
+
+# Check undo points available
+puts "\n6. Undo points available: #{replica.num_undo_points}"
+
+# Show what would be undone
+puts "\n7. Operations that would be undone:"
+undo_ops = replica.undo_operations
+puts "  Operations to undo: #{undo_ops.length}"
+undo_ops.to_a.each_with_index do |op, i|
+  puts "  #{i + 1}. #{op.operation_type}"
+end
+
+# Perform undo
+puts "\n8. Performing undo..."
+result = replica.undo!
+puts "  Undo successful: #{result}"
+
+# Show tasks after undo
+puts "\n9. Tasks after first undo:"
+tasks = replica.all_tasks
+if tasks.empty?
+  puts "  No tasks"
+else
+  tasks.each do |uuid, task|
+    puts "  - #{task.description} (#{uuid})"
+  end
+end
+
+# Show remaining undo points
+puts "\n10. Remaining undo points: #{replica.num_undo_points}"
+
+# Perform another undo
+if replica.num_undo_points > 0
+  puts "\n11. Performing second undo..."
+  result = replica.undo!
+  puts "   Undo successful: #{result}"
+
+  puts "\n12. Tasks after second undo:"
+  tasks = replica.all_tasks
+  if tasks.empty?
+    puts "   No tasks remaining"
+  else
+    tasks.each do |uuid, task|
+      puts "   - #{task.description} (#{uuid})"
+    end
+  end
+
+  puts "\n13. Final undo points: #{replica.num_undo_points}"
+else
+  puts "\n11. No more undo points available"
+end
+
+puts "\n=== Demo Complete ==="

data/ext/taskchampion/src/operations.rs

@@ -137,6 +137,15 @@ impl Operations {
         }
         Ok(())
     }
+
+    // Internal method for creating Operations from TaskChampion operations
+    pub(crate) fn from_tc_operations(tc_ops: Vec<taskchampion::Operation>) -> Self {
+        let mut operations = TCOperations::new();
+        for op in tc_ops {
+            operations.push(op);
+        }
+        Operations(ThreadBound::new(RefCell::new(operations)))
+    }
 }
 
 // Note: AsRef and AsMut cannot be implemented with RefCell

data/ext/taskchampion/src/replica.rs

@@ -93,6 +93,20 @@ impl Replica {
         Ok(hash)
     }
 
+    fn pending_tasks(&self) -> Result<RArray, Error> {
+        let mut tc_replica = self.0.get_mut()?;
+
+        let tc_tasks = tc_replica.pending_tasks().map_err(into_error)?;
+
+        let array = RArray::new();
+        for tc_task in tc_tasks {
+            let ruby_task = crate::task::Task::from_tc_task(tc_task);
+            array.push(ruby_task)?;
+        }
+
+        Ok(array)
+    }
+
     fn task_data(&self, uuid: String) -> Result<Value, Error> {
         let mut tc_replica = self.0.get_mut()?;
 
@@ -261,19 +275,37 @@ impl Replica {
         Ok(tc_replica.num_undo_points().map_err(into_error)?)
     }
 
-    fn pending_tasks(&self) -> Result<RArray, Error> {
+    fn get_task_operations(&self, uuid: String) -> Result<Value, Error> {
         let mut tc_replica = self.0.get_mut()?;
+        let tc_uuid = uuid2tc(&uuid)?;
 
-        let tc_tasks = tc_replica.pending_tasks().map_err(into_error)?;
+        let tc_operations = tc_replica.get_task_operations(tc_uuid).map_err(into_error)?;
+        let operations = Operations::from_tc_operations(tc_operations);
 
-        let array = RArray::new();
-        for tc_task in tc_tasks {
-            let ruby_task = crate::task::Task::from_tc_task(tc_task);
-            array.push(ruby_task)?;
-        }
+        Ok(operations.into_value())
+    }
 
-        Ok(array)
+    fn get_undo_operations(&self) -> Result<Value, Error> {
+        let mut tc_replica = self.0.get_mut()?;
+
+        let tc_operations = tc_replica.get_undo_operations().map_err(into_error)?;
+        let operations = Operations::from_tc_operations(tc_operations);
+
+        Ok(operations.into_value())
     }
+
+    fn commit_reversed_operations(&self, operations: &Operations) -> Result<bool, Error> {
+        let mut tc_replica = self.0.get_mut()?;
+
+        // Convert Operations to TaskChampion Operations
+        let tc_operations = operations.clone_inner()?;
+
+        // Commit the reversed operations
+        let success = tc_replica.commit_reversed_operations(tc_operations).map_err(into_error)?;
+
+        Ok(success)
+    }
+
 }
 
 pub fn init(module: &RModule) -> Result<(), Error> {
@@ -299,6 +331,9 @@ pub fn init(module: &RModule) -> Result<(), Error> {
     class.define_method("expire_tasks", method!(Replica::expire_tasks, 0))?;
     class.define_method("num_local_operations", method!(Replica::num_local_operations, 0))?;
     class.define_method("num_undo_points", method!(Replica::num_undo_points, 0))?;
+    class.define_method("get_task_operations", method!(Replica::get_task_operations, 1))?;
+    class.define_method("get_undo_operations", method!(Replica::get_undo_operations, 0))?;
+    class.define_method("commit_reversed_operations", method!(Replica::commit_reversed_operations, 1))?;
     class.define_method("pending_tasks", method!(Replica::pending_tasks, 0))?;
 
     Ok(())

data/ext/taskchampion/src/task.rs

@@ -255,6 +255,38 @@ impl Task {
         Ok(())
     }
 
+    fn remove_annotation(&self, annotation: &Annotation, operations: &crate::operations::Operations) -> Result<(), Error> {
+        let mut task = self.0.get_mut()?;
+        let entry_timestamp = annotation.as_ref().entry;
+
+        operations.with_inner_mut(|ops| {
+            task.remove_annotation(entry_timestamp, ops)
+        })?;
+        Ok(())
+    }
+
+    fn add_annotation_with_timestamp(&self, timestamp: Value, description: String, operations: &crate::operations::Operations) -> Result<(), Error> {
+        if description.trim().is_empty() {
+            return Err(Error::new(
+                crate::error::validation_error(),
+                "Annotation description cannot be empty or whitespace-only"
+            ));
+        }
+
+        let mut task = self.0.get_mut()?;
+        let entry = ruby_to_datetime(timestamp)?;
+
+        let annotation = taskchampion::Annotation {
+            entry,
+            description,
+        };
+
+        operations.with_inner_mut(|ops| {
+            task.add_annotation(annotation, ops)
+        })?;
+        Ok(())
+    }
+
     fn set_due(&self, due: Value, operations: &crate::operations::Operations) -> Result<(), Error> {
         let mut task = self.0.get_mut()?;
         let due_datetime = ruby_to_option(due, ruby_to_datetime)?;
@@ -293,6 +325,53 @@ impl Task {
         Ok(())
     }
 
+    fn set_timestamp(&self, property: String, timestamp: Value, operations: &crate::operations::Operations) -> Result<(), Error> {
+        if property.trim().is_empty() {
+            return Err(Error::new(
+                crate::error::validation_error(),
+                "Property name cannot be empty or whitespace-only"
+            ));
+        }
+
+        let mut task = self.0.get_mut()?;
+        let timestamp_datetime = ruby_to_option(timestamp, ruby_to_datetime)?;
+
+        // Convert timestamp to Unix timestamp string, or None for clearing
+        let timestamp_str = timestamp_datetime.map(|dt| dt.timestamp().to_string());
+
+        operations.with_inner_mut(|ops| {
+            task.set_value(&property, timestamp_str, ops)
+        })?;
+        Ok(())
+    }
+
+    fn get_timestamp(&self, property: String) -> Result<Value, Error> {
+        if property.trim().is_empty() {
+            return Err(Error::new(
+                crate::error::validation_error(),
+                "Property name cannot be empty or whitespace-only"
+            ));
+        }
+
+        let task = self.0.get()?;
+
+        // Get the value as string and attempt to parse as Unix timestamp
+        match task.get_value(&property) {
+            Some(timestamp_str) => {
+                // Parse the string as Unix timestamp (seconds since epoch)
+                if let Ok(timestamp_secs) = timestamp_str.parse::<i64>() {
+                    use chrono::{DateTime, Utc};
+                    if let Some(dt) = DateTime::from_timestamp(timestamp_secs, 0) {
+                        return datetime_to_ruby(dt);
+                    }
+                }
+                // If parsing fails, return nil
+                Ok(().into_value())
+            },
+            None => Ok(().into_value()) // Return nil if property doesn't exist
+        }
+    }
+
     fn set_uda(&self, namespace: String, key: String, value: String, operations: &crate::operations::Operations) -> Result<(), Error> {
         if namespace.trim().is_empty() {
             return Err(Error::new(
@@ -397,9 +476,13 @@ pub fn init(module: &RModule) -> Result<(), Error> {
     class.define_method("add_tag", method!(Task::add_tag, 2))?;
     class.define_method("remove_tag", method!(Task::remove_tag, 2))?;
     class.define_method("add_annotation", method!(Task::add_annotation, 2))?;
+    class.define_method("remove_annotation", method!(Task::remove_annotation, 2))?;
+    class.define_method("add_annotation_with_timestamp", method!(Task::add_annotation_with_timestamp, 3))?;
     class.define_method("set_due", method!(Task::set_due, 2))?;
     class.define_method("set_entry", method!(Task::set_entry, 2))?;
     class.define_method("set_value", method!(Task::set_value, 3))?;
+    class.define_method("set_timestamp", method!(Task::set_timestamp, 3))?;
+    class.define_method("get_timestamp", method!(Task::get_timestamp, 1))?;
     class.define_method("set_uda", method!(Task::set_uda, 4))?;
     class.define_method("delete_uda", method!(Task::delete_uda, 3))?;
     class.define_method("done", method!(Task::done, 1))?;

data/lib/taskchampion/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Taskchampion
-  VERSION = "0.7.0"
+  VERSION = "0.9.0"
 end

data/lib/taskchampion.rb

@@ -37,5 +37,52 @@ module Taskchampion
       ws.replica = self
       ws
     end
+
+    # Ruby-style convenience methods for undo functionality
+    def task_operations(uuid)
+      get_task_operations(uuid)
+    end
+
+    def undo_operations
+      get_undo_operations
+    end
+
+    def commit_undo!(operations)
+      commit_reversed_operations(operations)
+    end
+
+    def undo!
+      ops = undo_operations
+      return false if ops.empty?
+      commit_undo!(ops)
+    end
+  end
+
+  # Task convenience methods
+  class Task
+    # Update an existing annotation's description while preserving its timestamp
+    #
+    # This is a convenience method that removes the old annotation and adds a new one
+    # with the same timestamp, effectively updating the description while maintaining
+    # the original creation time for chronological history.
+    #
+    # @param annotation [Taskchampion::Annotation] The annotation to update
+    # @param new_description [String] The new description text
+    # @param operations [Taskchampion::Operations] Operations collection
+    # @return [void]
+    #
+    # @example Update an annotation
+    #   annotation = task.annotations.first
+    #   task.update_annotation(annotation, "Updated note", operations)
+    #   replica.commit_operations(operations)
+    #
+    # @raise [Taskchampion::ValidationError] if new_description is empty or whitespace-only
+    def update_annotation(annotation, new_description, operations)
+      # Remove the old annotation
+      remove_annotation(annotation, operations)
+
+      # Add new annotation with the preserved timestamp
+      add_annotation_with_timestamp(annotation.entry, new_description, operations)
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: taskchampion-rb
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Tim Case
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-18 00:00:00.000000000 Z
+date: 2025-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys
@@ -41,9 +41,11 @@ files:
 - Cargo.toml
 - README.md
 - Rakefile
+- docs/ANNOTATION_IMPLEMENTATION.md
 - docs/API_REFERENCE.md
 - docs/THREAD_SAFETY.md
 - docs/breakthrough.md
+- docs/date_conversion_analysis.md
 - docs/description.md
 - docs/errors.md
 - docs/phase_3_plan.md
@@ -52,6 +54,7 @@ files:
 - examples/basic_usage.rb
 - examples/pending_tasks.rb
 - examples/sync_workflow.rb
+- examples/undo_demo.rb
 - ext/taskchampion/Cargo.toml
 - ext/taskchampion/extconf.rb
 - ext/taskchampion/src/access_mode.rs