Events & Replay

The event log

Every state change in Cosmictron flows through a single, append-only event log (the Write-Ahead Log). The event log is:

• Ordered — every event has a monotonically increasing sequence number
• Durable — written to disk before the reducer returns (in always fsync mode)
• Checksummed — each segment is checksummed for integrity
• Cross-modal — database mutations, tool calls, voice turns, and A2A messages all share the same sequence space

This is the foundation for deterministic replay.

Deterministic replay

Given the same event log, Cosmictron can reconstruct the exact state of any session at any point in time. This means:

• Debugging: rewind to the moment before a bug occurred and inspect state
• Compliance: prove to an auditor exactly what happened during a regulated workflow
• Testing: replay a production incident in a staging environment

How replay works

1. Start with a snapshot (checkpoint) at time T₀
2. Re-apply all events from T₀ to T₁ in order
3. The resulting state is identical to what was live at T₁

Because reducers are pure functions of (state, event), replay is guaranteed to produce the same output. There are no external side-effects that can change the outcome (HTTP calls from reducers are logged as events themselves).

Time-travel queries

The query engine supports time-travel at the SQL level:

-- State as of a specific transaction
SELECT * FROM agent_state AS OF TX 1234567;

-- State as of a specific timestamp
SELECT * FROM agent_state AS OF TIMESTAMP '2026-01-15T10:30:00Z';

The compliance chain

When the compliance layer is enabled, the event log gains additional guarantees:

Event N-1 ──hash──► Event N ──hash──► Event N+1
             │                │
        Ed25519 sig      Ed25519 sig
             │                │
        RFC 3161 ts      RFC 3161 ts

Each event includes:

• The SHA-256 hash of the previous event (chain link)
• An Ed25519 signature over (hash, timestamp, content)
• Optionally, an RFC 3161 timestamp from a trusted TSA

This makes the log tamper-evident: modifying any event breaks the hash chain and the signature.

Event schema

A signed event in the log contains:

Field	Type	Description
seq	u64	Monotonically increasing sequence number
reducer	string	Name of the reducer that produced this event
sender_identity	bytes	Identity of the caller
timestamp	i64	Unix microseconds
content_hash	bytes[32]	SHA-256 of the event payload
prev_hash	bytes[32]	SHA-256 of the previous event
signature	bytes[64]	Ed25519 signature
tsa_token	bytes?	RFC 3161 timestamp token (optional)

Audit bundle export

An audit bundle is a self-contained export of events for a given time range or session:

cosmictron-cli audit export \
  --session-id session-abc \
  --from 2026-01-01 \
  --to 2026-01-31 \
  --output audit-jan-2026.bundle

The bundle contains:

• All events in the range, with signatures and hashes
• The signing key’s public key certificate chain
• Verification metadata (TSA tokens, FROST threshold signature)

Recipients can verify the bundle without connecting to the server. See Audit Bundles.

Note

Deterministic replay applies to the state model (tables). Side-effects such as outbound HTTP calls are recorded as events and not re-executed during replay — they are replayed as logged results.