Timeline

Platform unified audit sink plus HLC-ordered event timeline (queries, critical path analysis, deterministic replay).

Purpose

Timeline serves two roles in one deployable Stella Ops service:

1. Platform-wide unified audit sink. Every Stella Ops service pushes audit events to POST /api/v1/audit/ingest, where they are persisted in timeline.unified_audit_events with a per-tenant SHA-256 hash chain for tamper evidence, then served back with filtering, statistics, correlation clustering, retention/GDPR controls, and an anomaly-detection (anomaly v2) subsystem.
2. HLC event timeline. Hybrid Logical Clock-ordered event queries, critical-path analysis for latency diagnosis, and deterministic replay.

The TimelineIndexer ingestion side was consolidated into this module and runs in-process.

Quick Links

• Architecture
• API Reference - autogenerated from timeline/openapi/v1.json
• Anomaly v2
• Audit retention
• Audit emitter coverage

Status

Key Features

• Unified, tamper-evident audit sink (timeline.unified_audit_events, per-tenant SHA-256 hash chain via the timeline.next_unified_audit_sequence / timeline.verify_unified_audit_chain functions) for all services
• Audit query, statistics, free-text timeline search, correlation clustering, and hash-chain verification
• Data classification + scheduled retention purge and GDPR Art. 17 right-to-erasure (actor PII redaction that preserves the hash chain)
• Anomaly v2 detection: 10 built-in rule kinds (unusual volume, failed-auth spike, privilege escalation, off-hours activity, unusual pattern, per-actor volume z-score, new actor IP, actor-action novelty, off-hours policy, escalation chain), tenant-scoped configurable rules, actor-behavior baselines, and a Notify dispatch worklist
• HLC-based causal event ordering and correlation ID queries
• Critical path analysis (latency stages)
• Event export (NDJSON/JSON, optional DSSE signing) and deterministic replay (dry-run/verify modes; available in Development/Testing, production fails closed with HTTP 501 pending durable storage)
• TimelineIndexer query/evidence-linkage endpoints (consolidated in-process)

Dependencies

Upstream

• Eventing infrastructure (StellaOps.Eventing) - HLC event storage and indexing
• HybridLogicalClock library - causal timestamp generation and comparison
• All services (via StellaOps.Audit.Emission) - push audit events to the unified sink

Downstream

• Platform - timeline and audit views for operator dashboards
• CLI - event query commands
• Web - timeline/audit UI components
• Notify - consumes pending anomaly alerts (dispatch worklist)

Note: Timeline is a single deployable service. The TimelineIndexer ingestion side was merged into it and runs in-process; the standalone StellaOps.TimelineIndexer.WebService / StellaOps.TimelineIndexer.Worker projects are dormant.

API Surface

The service exposes four route families (see API Reference for the full operation list). All payloads are tenant-scoped; the tenant is resolved from the authenticated identity’s stellaops:tenant claim. Raw X-StellaOps-TenantId / x-tenant-id headers are never accepted as tenancy sources.

• HLC timeline — GET /api/v1/timeline/hlc/{correlationId}, GET /api/v1/timeline/hlc/{correlationId}/critical-path.
• HLC export & replay — POST /api/v1/timeline/hlc/{correlationId}/export (NDJSON/JSON, optional DSSE), GET /api/v1/timeline/hlc/export/{exportId} (+ /download); POST /api/v1/timeline/hlc/{correlationId}/replay, GET /api/v1/timeline/hlc/replay/{replayId}, POST .../cancel, DELETE .../{replayId}.
• Unified audit — POST /api/v1/audit/ingest; GET /api/v1/audit/events (+ /{eventId}), /stats, /timeline/search, /correlations (+ /{correlationId}), /chain/verify, /retention-policies; anomalies (/anomalies, /anomalies/{alertId}/acknowledge, /anomalies/_pending-dispatch, /anomalies/{alertId:guid}/dispatched, /anomalies/{alertId:guid}/dispatch-failed, and CRUD under /anomalies/rules); POST /api/v1/audit/export (+ GET .../{exportId}); DELETE /api/v1/audit/actors/{actorId}/pii (GDPR right-to-erasure).
• TimelineIndexer — GET /api/v1/timeline (+ /{eventId}, /{eventId}/evidence) and POST /api/v1/timeline/events, each also mounted at the bare prefix (/timeline, …) for direct access.

Authorization

Endpoints are gated by named policies that map to timeline:* OAuth scopes (registered in Program.cs via AddStellaOpsScopePolicy; scope constants live in StellaOpsScopes):

Runtime Contract

• Outside Testing, Timeline ingestion must have at least one real transport enabled: Ingestion:Nats:Enabled=true or Ingestion:Redis:Enabled=true (enforced at startup by AddTimelineIngestionRuntime; a missing transport fails the host build).
• The null ingestion subscriber (NullTimelineEventSubscriber) is reserved for the Testing environment and is not a live fallback.
• Replay and export bundle building are only registered for Development/Testing; in other environments the Unsupported* implementations return HTTP 501 (timeline_replay_unavailable / timeline_export_unavailable).