Replay events and query derived state

Single event replay

Re-process one specific event through current workflow rules:

POST /replay
{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "skip_external_side_effects": true
}

Use cases: test a fixed WASM action against a past event, backfill a missed projection update, verify new workflow behavior on historical data.

Bulk replay

Replay many events matching filters:

POST /replay/bulk
{
  "event_ids": ["uuid-1", "uuid-2"],
  "event_type": "payment.failed",
  "since": "2025-01-01T00:00:00Z",
  "until": "2025-01-31T23:59:59Z",
  "skip_external_side_effects": true,
  "limit": 100
}

Full database rebuild

POST /projections/rebuild

Resets all projection state for the organization/environment, then replays the entire event history with side effects suppressed. Use when projection logic has fundamentally changed or tables are corrupted.

The dashboard at /dashboard/replay shows rebuild progress. Production environments may require reauthentication.

Side-effect suppression

During replay, the worker checks replay_skip_side_effects in event metadata. When enabled:

• webhook_dispatch steps are skipped (no external HTTP calls)
• projection_write steps execute normally (state rebuilds)
• emit_event steps execute normally (internal derived events)
• wasm_action steps execute normally (business logic runs)

This guarantees replays never re-charge customers, send duplicate emails, or spam external APIs.

Projections

Projections are materialized read-model views derived from the event stream. They transform immutable events into queryable state.

Query projections

GET /projections
GET /projections?projection=service_health&environment=production

Key properties

• Disposable — projections can be dropped and rebuilt from events at any time
• Deterministic — same events always produce same state: state = f(events)
• Project-scoped — isolated by organization and project context

Dead Letter Queue

Events that fail processing (schema violations, WASM crashes, timeout, exhausted retries) are quarantined in the DLQ rather than lost.

GET  /dead-letter-events              # List quarantined events
POST /platform/dead-letter-events/clear  # Reprocess all

The dashboard provides a visual interface at /dashboard/admin for inspection and 1-click reprocessing.

SDK usage

// TypeScript
await client.replay.single('event-uuid', {
  skipExternalSideEffects: true,
});

await client.replay.bulk({
  eventType: 'payment.failed',
  since: '2025-01-01T00:00:00Z',
  limit: 50,
});

const projections = await client.projections.query({
  projection: 'service_health',
});

const deadLetters = await client.dlq.list();