Task Persistence Test Guide

Status note (documentation review): scripts/test_reasoning_protection.py no longer exists in the repository. This guide documents the ad hoc diagnostic script and methodology used to investigate a past task/issue/result persistence bug; it is kept as a reference for reproducing a similar diagnostic script if a similar persistence issue needs investigating again, not as a currently runnable test.

Overview

The enhanced test script now includes three critical persistence tests (Tests 5-7) that simulate the real Thalabus workflow where task/issue/result data is being lost.

Test 5: Task Persistence Cycle (CRITICAL)

What it tests:

1. Create a task with initial status (TS_OPEN)
2. Update task status to TS_IN_PROGRESS  
3. Update task description
4. Read task back and verify changes persisted

Expected behavior: - ✅ Task status should be TS_IN_PROGRESS (not TS_OPEN) - ✅ Task description should be "Updated task description"

If this fails: - Task data is being lost between write and read operations - Likely cause: write_context not actually saving changes - Check: Is update_document_in_neo4j() being called? Is the cache being updated?

Test 6: Issue Persistence Cycle

What it tests:

1. Create issue with severity=MEDIUM, status=OPEN
2. Update issue severity to HIGH
3. Update issue status to IN_PROGRESS
4. Update issue description
5. Read issue back and verify all changes persisted

Expected behavior: - ✅ Issue status should be IN_PROGRESS - ✅ Issue severity should be HIGH - ✅ Issue description should be "Updated issue description"

If this fails: - Issue modifications are not persisting - Check if issues are part of the Neo4j save process

Test 7: Result Persistence Cycle

What it tests:

1. Create result for a task with initial content
2. Update result content
3. Read result back and verify content persisted

Expected behavior: - ✅ Result content should be "Updated result content with more details"

If this fails: - Result modifications are not persisting - Check if results are properly linked to divisions

How to Run

# Activate environment
.venv\Scripts\Activate.ps1

# Run the full test suite
python scripts\test_reasoning_protection.py

What to Look For in Output

Success Case:

TEST 5: Task Persistence Cycle (Write → Update → Read)
...
✓ Task found: t-005
Status: ts_in_progress
Description: Updated task description

✓ Status persisted correctly: ts_in_progress
✓ Description persisted correctly

✓ Task persistence test PASSED

Failure Case:

TEST 5: Task Persistence Cycle (Write → Update → Read)
...
✓ Task found: t-005
Status: ts_open  ❌ WRONG! Should be ts_in_progress
Description: Initial task description  ❌ WRONG! Should be updated

❌ Status NOT persisted! Expected TS_IN_PROGRESS, got ts_open
❌ Description NOT persisted! Expected 'Updated task description', got 'Initial task description'

❌ Task persistence test FAILED - data loss detected!

Debugging Persistence Issues

If tests 5-7 fail, check:

1. Write Operations

# Are changes actually being made in write_context?
with doc.write_context(lock):
    task.set_status(TaskStatus.TS_IN_PROGRESS)  # Does this log an error?
    # Check: Is _check_write_allowed() returning True?
    # Check: Are setters actually updating internal state?

2. Neo4j Save

# Is the document being saved to Neo4j?
def update_document_in_neo4j(self) -> bool:
    # Should execute Neo4j MERGE query
    # Should update self._rdoc_last_update
    # Check logs for "Successfully updated ReasoningDocument"

3. Cache Updates

# Is the cache being updated after write?
# In write_context exit (line ~1479):
if self._rdoc_lock_depth == 1:
    success = self.update_document_in_neo4j()
    if success:
        self._cache_document(self)  # This should happen
        # Check logs for "Cached document"

4. Read Operations

# Are reads using fresh data?
with doc.read_context():
    # Check logs: "Using cached document state..." or "loading from Neo4j"
    task = div.get_task_by_id("t-005")
    status = task.status()  # Should read fresh value

Expected Log Output (Verbose)

When running with proper debug logging, you should see:

DEBUG: Using cached document state for write_context on document test-doc-005
DEBUG: Reloaded fresh document state for document test-doc-005
DEBUG: Successfully saved document test-doc-005 to Neo4j after write operations
DEBUG: Cached document test-doc-005 (timestamp: 1234567890.123)

DEBUG: Using cached document state for read_context on document test-doc-005
DEBUG: Document test-doc-005 is up-to-date, skipping reload (cache/timestamp optimization)

Common Failure Patterns

Pattern 1: "Task found but status is wrong"

→ Setter is not being called, or being called outside write_context → Check: Is task._rt_status being updated but not saved?

Pattern 2: "Task not found after write_context"

→ Division.add_task() is failing or not linking parent → Check: Is _rt_parent_division being set correctly?

Pattern 3: "All updates fail"

→ write_context() is not being entered → Check: Is document_lock being acquired properly?

Interpreting Results

Exit code from test script: - 0 (SUCCESS): All persistence tests passed - data is being preserved correctly - 1 (FAILURE): Some persistence tests failed - data loss detected

Check the test output to identify which specific operations are failing: - ❌ in test output indicates which assertion failed - Look at the actual vs expected values to understand the issue

Next Steps

If persistence tests fail:

  1. Enable DEBUG logging to see all cache/Neo4j operations
  2. Add print statements in write_context/read_context to verify flow
  3. Check Neo4j directly to see if documents are actually being saved
  4. Verify timestamps are being set correctly (needed for cache invalidation)
  5. Test with simpler operations (just status, then add description, etc.)

Additional Notes

These tests create fresh in-memory documents without hitting Neo4j, so they test the core persistence logic in isolation. If these tests pass but real Thalabus operation fails, the issue is likely in: - Neo4j connection/query execution - DocumentTemplate vs ReasoningDocument node type differences - External factors (concurrent writes, stale cache)