# Timeline forensics

Purpose
- Provide an append-only event ledger for audit, replay, and incident analysis.
- Support deterministic exports for offline review.

Event model
- event_id (ULID)
- tenant
- timestamp (UTC ISO-8601)
- category (scanner, policy, runtime, evidence, notify)
- details (JSON payload)
- trace_id for correlation

Event kinds
- scan.completed
- policy.verdict
- attestation.verified
- evidence.ingested
- notify.sent
- runtime.alert
- redaction_notice (compensating event)

APIs
- GET /api/v1/timeline/events with filters for tenant, category, time window, trace_id.
- GET /api/v1/timeline/events/{id} for a single event.
- GET /api/v1/timeline/export for NDJSON exports.
- Headers: X-Stella-Tenant, optional X-Stella-TraceId, If-None-Match.

Query guidance
- Use category plus trace_id to track scan to policy to notify flow.
- Use tenant and timestamp ranges for SLA audits.
- CLI parity: stella timeline list mirrors the API.

Retention and redaction
- Append-only storage; no deletes.
- Redactions use redaction_notice events that reference the superseded event.
- Retention is tenant-configurable and exported weekly to cold storage.

Offline posture
- Offline kits include timeline exports for compliance review.
- Exports include stable ordering and manifest hashes.

Related references
- security/forensics-and-evidence-locker.md
- observability.md
- docs/forensics/timeline.md