Core Concepts

Agent time travel

Historical reads, run replay, and branches from prior snapshots show what an agent saw and what changed later.

Overview

Agent time travel ties historical reads to capability invocations. It answers: what database state did the capability see, what would it do now, and what changed after the decision?

The run id used here is produced by Synapsor when you invoke a capability. Store the returned agent_run_id or run_resource with the user-visible answer/proposal, or query synapsor_agent_runs later by trace_id.

AS OF queries are read-only. If a reviewer needs to test a fix from an old snapshot, create a branch from the agent run, version, or timestamp.

Do not silently fall back to current rows when a snapshot is expired. Replay and audit depend on proving the requested historical state is still retained.

Developer notes

Use original replay for audits and current replay for regression checks.
Create branches from historical snapshots when investigation needs writable state.
Grant READ on agent-run resources before exposing replay to auditors.
Treat SNAPSHOT_EXPIRED as a hard failure, not a reason to read current state.

Historical SQL

SQL

-- 42 is a retained database/catalog version from Synapsor metadata.
AS OF VERSION 42
SELECT * FROM expenses WHERE expense_id = 'EXP-1001'; -- app-domain row id

-- Timestamps are read-only selectors and must still be inside retention.
AS OF TIMESTAMP '2026-05-14T10:30:00Z'
SELECT * FROM expense_policies WHERE policy_id = 'meal_policy'; -- policy row id

-- 123 is the agent_run_id returned by a prior capability invocation.
AS OF AGENT RUN '123'
SELECT * FROM expense_policies WHERE policy_id = 'meal_policy'; -- what run 123 saw

Examples

http

POST /v1/agent/runs/replay
Authorization: Bearer <database-api-key>
Content-Type: application/json

{
  "run_id": 123,
  "session": {
    "tenant_id": "acme",
    "principal": "auditor_01"
  },
  "mode": "original_snapshot"
}