# Hybrid Logical Clock (HLC) Audit-Safe Job Queue Ordering

## Module
Timeline

## Status
IMPLEMENTED

## Description
HLC-based global job ordering for distributed deployments, replacing wall-clock timestamps. Includes HLC core library (PhysicalTime+NodeId+LogicalCounter), Scheduler queue chain integration with chain-linked audit logs, offline merge protocol for air-gapped job synchronization with deterministic merge and conflict resolution, and cross-module integration tests.

## Implementation Details
- **TimelineQueryService**: `src/Timeline/__Libraries/StellaOps.Timeline.Core/TimelineQueryService.cs` -- queries events by correlation ID with HLC range filtering (FromHlc/ToHlc); GetByCorrelationIdAsync supports limit/offset pagination, service/kind filtering; HLC-based cursor pagination via ToSortableString(); CountByCorrelationIdAsync for total counts
- **ITimelineQueryService**: `src/Timeline/__Libraries/StellaOps.Timeline.Core/ITimelineQueryService.cs` -- interface: GetByCorrelationIdAsync, GetCriticalPathAsync, GetByServiceAsync
- **TimelineEndpoints**: `src/Timeline/StellaOps.Timeline.WebService/Endpoints/TimelineEndpoints.cs` -- REST API at `/api/v1/timeline`: GET /{correlationId} (query with limit, offset, fromHlc, toHlc, services, kinds filters; returns TimelineResponse with events, totalCount, hasMore, nextCursor), GET /{correlationId}/critical-path (returns stages sorted by duration descending)
- **HlcTimestamp**: referenced from `StellaOps.HybridLogicalClock` namespace -- Parse, TryParse, ToSortableString for HLC values
- **TimelineEvent**: referenced from `StellaOps.Eventing.Models` -- EventId, THlc (HlcTimestamp), TsWall (wall-clock), Service, Kind, Payload, PayloadDigest, EngineVersion (EngineName/Version/SourceDigest), CorrelationId, SchemaVersion
- **ITimelineEventStore**: referenced from `StellaOps.Eventing.Storage` -- persistence: GetByCorrelationIdAsync, GetByHlcRangeAsync, GetByServiceAsync, CountByCorrelationIdAsync
- **TimelineMetrics**: `src/Timeline/__Libraries/StellaOps.Timeline.Core/Telemetry/TimelineMetrics.cs` -- OpenTelemetry metrics for timeline operations
- **Tests**: `src/Timeline/__Tests/StellaOps.Timeline.Core.Tests/TimelineQueryServiceTests.cs`, `src/Timeline/__Tests/StellaOps.Timeline.WebService.Tests/TimelineApiIntegrationTests.cs`
- **Source**: SPRINT_20260105_002_000_INDEX_hlc_audit_safe_ordering.md

## E2E Test Plan
- [ ] GET /api/v1/timeline/{correlationId} returns HLC-ordered events with correct pagination
- [ ] Verify HLC range filtering (fromHlc/toHlc) returns only events within the specified range
- [ ] Test service and kind filters narrow results correctly
- [ ] Verify cursor-based pagination using nextCursor (HLC sortable string)
- [ ] Verify events are ordered by HLC timestamp, not wall-clock time
- [ ] Test critical path analysis returns stages sorted by duration descending with percentage
- [ ] Verify deterministic event IDs are consistent across queries