stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
5593212b414864ab213082c8945a267451b99901
git.stella-ops.org/docs/features/checked/timeline/hybrid-logical-clock-audit-safe-job-queue-ordering.md

3.4 KiB
Raw Blame History

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

Module

Timeline

Status

VERIFIED

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

Verification

Run ID: run-001 Date: 2026-02-10 Verdict: PASS

Implementation Verification:

  • HLC deeply integrated: HlcTimestamp (PhysicalTime+NodeId+LogicalCounter) for ordering
  • Range filtering via FromHlc/ToHlc parameters
  • Cursor pagination via ToSortableString()
  • Unit tests verify HLC ordering explicitly

Test Execution:

  • All HLC ordering tests PASS
  • Range filtering tests PASS
  • Cursor pagination tests PASS

Build Status:

  • 0 errors
  • 0 warnings
  • Build: PASS

Overall Verdict: PASS