stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
1bf6bbf3955ecbd8d20f5eeb767da5c7f8324b57
git.stella-ops.org/src/Timeline/AGENTS.md

2.4 KiB
Raw Blame History

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 - Code quality rules (especially 8.2 TimeProvider, 8.18 DateTimeOffset, 8.19 HLC)
  2. docs/modules/eventing/event-envelope-schema.md
  3. 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

{"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