# Timeline Module - AGENTS.md

## Module Overview

The Timeline module provides a unified event timeline service for querying, replaying, and exporting HLC-ordered events across all StellaOps services.

## Roles Expected

- **Backend Engineer**: Implement API endpoints, query services, and replay orchestration
- **QA Engineer**: Create integration tests with Testcontainers PostgreSQL

## Key Documentation

Before working on this module, read:

1. [CLAUDE.md](../../CLAUDE.md) - Code quality rules (especially 8.2 TimeProvider, 8.18 DateTimeOffset, 8.19 HLC)
2. [docs/modules/eventing/event-envelope-schema.md](../../docs/modules/eventing/event-envelope-schema.md)
3. [docs/modules/scheduler/hlc-ordering.md](../../docs/modules/scheduler/hlc-ordering.md)

## Working Agreements

### Directory Ownership

- **WebService**: `src/Timeline/StellaOps.Timeline.WebService/`
- **Core Library**: `src/Timeline/__Libraries/StellaOps.Timeline.Core/`
- **Tests**: `src/Timeline/__Tests/`

### Dependencies

- Depends on: `StellaOps.Eventing`, `StellaOps.HybridLogicalClock`, `StellaOps.Replay.Core`
- Consumed by: UI Console (Timeline view), CLI (replay commands)

### API Conventions

1. All endpoints under `/api/v1/timeline`
2. HLC timestamps returned as sortable strings
3. Pagination via `limit`, `offset`, and `nextCursor`
4. Export produces NDJSON by default

### Testing Requirements

1. Unit tests with `[Trait("Category", "Unit")]`
2. Integration tests with `[Trait("Category", "Integration")]`
3. Use `FakeTimeProvider` for deterministic tests
4. Use Testcontainers for PostgreSQL integration tests

## Module-Specific Rules

### HLC Ordering

- All queries return events ordered by HLC timestamp (ascending)
- Critical path analysis uses wall-clock duration but references HLC for linking
- Replay must preserve HLC ordering

### Export Format

```ndjson
{"event_id":"abc123","t_hlc":"1704585600000:0:node1","correlation_id":"scan-1","kind":"ENQUEUE",...}
{"event_id":"def456","t_hlc":"1704585600001:0:node1","correlation_id":"scan-1","kind":"EXECUTE",...}
```

### Replay Contract

- Replay is read-only (dry-run mode)
- Verify mode compares replayed state to stored state
- Replay operations are idempotent

## Service Endpoints
- Development: https://localhost:10240, http://localhost:10241
- Local alias: https://timeline.stella-ops.local, http://timeline.stella-ops.local
- Env var: STELLAOPS_TIMELINE_URL