Time Travel Deep Dive

What you'll learn

Query the exact state of a strand at any past moment, understand the HLC, and build audit snapshots.

How time travel works

Every record's ts_hlc is immutable. as_of simply filters to records where ts_hlc ≤ your_timestamp. No separate history table. No changelog to maintain. It just works.

Capture a point in time

import time
# Current HLC
now_hlc = int(time.time() * 1000) * 65536
print(now_hlc)

Write some records, capture HLC between them

`bash # Write record A — note the ts_hlc from response HASH_A=$(curl -s -X POST http://localhost:7475/v1/agents/inventory/write \ -H "Content-Type: application/json" \ -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \ -d '{"payload": {"item": "widget", "qty": 100}}' \ | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['content_hash'])")

# Capture HLC now (between A and B) MIDPOINT_HLC=$(python3 -c "import time; print(int(time.time()*1000)*65536)")

# Write record B (newer) curl -s -X POST http://localhost:7475/v1/agents/inventory/write \ -H "Content-Type: application/json" \ -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \ -d '{"payload": {"item": "widget", "qty": 75, "note": "sold 25 units"}}' \ | python3 -m json.tool

# as_of MIDPOINT — only record A is visible curl -s -X POST http://localhost:7475/v1/agents/inventory/query \ -H "Content-Type: application/json" \ -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \ -d "{\"type\": \"as_of\", \"ts_hlc\": $MIDPOINT_HLC, \"limit\": 100}" \ | python3 -m json.tool `

Production patterns

Daily compliance snapshot: `python import time, datetime

def end_of_day_hlc(date: datetime.date) -> int: # End of day UTC in HLC dt = datetime.datetime(date.year, date.month, date.day, 23, 59, 59) unix_ms = int(dt.timestamp() * 1000) return unix_ms * 65536 `

"What did the AI agent see when it made decision X?": - Every AI decision is written as a record with decided_at_hlc - Replay: query all data agents as_of that HLC → you see exactly what the agent saw

Challenge

Simulate an inventory system. Write 5 qty-change records. Take HLC snapshots between them. Use as_of to reconstruct the state after each individual write.

---