stemedb/uat/consumer-health/guidance-change-propagation.md

UAT: Guidance Change Propagation ("What Changed Since?")

Date: YYYY-MM-DD Feature: Incremental Change Tracking Status: [ ] PASS / [ ] FAIL / [ ] BLOCKED

Scenario

A downstream application queried StemeDB at time T1. Now at T2, they want to know: "What changed since my last query?"

This is critical for:

• Keeping derived data in sync
• Audit trails
• Real-time dashboards

Acceptance Criteria

Criterion	Expected	Met?
Initial query at T1	Returns baseline	[ ]
New assertion added	Stored with timestamp	[ ]
since=T1 query	Returns only new assertion	[ ]
Changes array format	Includes operation type	[ ]
No false positives	Old assertions not returned	[ ]

Test Matrix

Step	Action	Expected	Actual	Status
1	Query at T1	Baseline returned		[ ]
2	Add new assertion	Hash returned		[ ]
3	Query with since=T1	Only new assertion		[ ]
4	Add another assertion	Hash returned		[ ]
5	Query with since=T1	Both new assertions		[ ]
6	Query with since=T2	Only most recent		[ ]

Setup Commands

# Start StemeDB
cargo run --bin stemedb-api &
sleep 2

Test Commands

Step 1: Establish Baseline at T1

# Record the current timestamp
T1=$(date +%s)

# Create initial assertion
curl -X POST http://localhost:18180/v1/assertions \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Semaglutide",
    "predicate": "approved_indications",
    "object": {"Text": "Type 2 Diabetes"},
    "confidence": 1.0,
    "source_class": "Regulatory"
  }'

# Query baseline
curl "http://localhost:18180/v1/query?subject=Semaglutide&predicate=approved_indications"

Expected: Returns Type 2 Diabetes assertion Actual: Status: [ ]

Step 2: Add New Assertion After T1

# Wait a moment to ensure different timestamp
sleep 1

# FDA approves new indication
curl -X POST http://localhost:18180/v1/assertions \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Semaglutide",
    "predicate": "approved_indications",
    "object": {"Text": "Chronic Weight Management"},
    "confidence": 1.0,
    "source_class": "Regulatory"
  }'

Expected: Hash returned Actual: Status: [ ]

Step 3: Query with since=T1

curl "http://localhost:18180/v1/changes?subject=Semaglutide&since=$T1"

Expected:

{
  "changes": [
    {
      "operation": "insert",
      "subject": "Semaglutide",
      "predicate": "approved_indications",
      "object": {"Text": "Chronic Weight Management"},
      "timestamp": ...,
      "hash": "..."
    }
  ],
  "query_timestamp": ...,
  "since_timestamp": T1
}

Actual: Status: [ ]

Step 4: Add Another Assertion

T2=$(date +%s)
sleep 1

# Third indication approved
curl -X POST http://localhost:18180/v1/assertions \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Semaglutide",
    "predicate": "approved_indications",
    "object": {"Text": "Cardiovascular Risk Reduction"},
    "confidence": 1.0,
    "source_class": "Regulatory"
  }'

Expected: Hash returned Actual: Status: [ ]

Step 5: Query with since=T1 (All Changes)

curl "http://localhost:18180/v1/changes?subject=Semaglutide&since=$T1"

Expected: Returns BOTH new assertions (Weight Management AND Cardiovascular) Actual: Status: [ ]

Step 6: Query with since=T2 (Most Recent Only)

curl "http://localhost:18180/v1/changes?subject=Semaglutide&since=$T2"

Expected: Returns ONLY Cardiovascular Risk Reduction Actual: Status: [ ]

Sign-Off Checklist

• Baseline query works
• New assertions timestamped correctly
• since= filter returns only newer assertions
• Changes include operation type
• Timestamp precision is sufficient (second or better)

Notes

The /changes endpoint is separate from /query to distinguish between "current state" and "what changed" semantics.

---

Tester: Date: Result: