Prepare the new score::time API

[lavrovvalera]

score::time — Unified Clock API (new Clock<Tag> framework)

Ref: #9

Summary

Introduces score::time — a unified, tag-based clock API that replaces the
SynchronizedVehicleTime and HighPrecisionLocalSteadyClock class hierarchies with a
single, scalable template wrapper Clock<Tag>. All four clock domains (vehicle time,
HPLS, steady, system) are accessible through the same call pattern. Legacy packages are
marked deprecated and will be removed once TimeDaemon consumers have migrated.

---

Motivation

The existing API had several pain points across safe-posix-platform and ddad consumers:

• Two unrelated APIs — SynchronizedVehicleTime::FactoryImpl and
  HighPrecisionLocalSteadyClock::FactoryImpl had completely different construction patterns.
• Factory injection in SUTs — components took factory objects as constructor parameters,
  requiring test-specific constructor signatures.
• Mutable TimeStatus snapshot — public data members, raw-uint64_t constructors, and
  non-const accessors triggered Coverity M11-0-1 suppressions.
• Four named callback methods — Set*/Unset* for each PTP event type; no generic
  subscription pattern.
• No steady_clock / system_clock unification — callers mixed std::chrono clocks and
  BMW-specific clocks with incompatible APIs.

---

Changes

New framework — score/time/clock/

Header	Purpose
clock.h	Clock<Tag> value wrapper — Now(), Subscribe<E>(), IsAvailable(), GetInstance()
clock_traits.h	ClockTraits<Tag> primary template + std::chrono specialisations
clock_override_guard.h	ClockOverrideGuard<Tag> RAII guard for test mock injection
clock_snapshot.h	ClockSnapshot<TimepointT, StatusT> immutable two-field snapshot
clock_status.h	ClockStatus<FlagEnumT> bit-flag status utility
no_status.h	NoStatus empty placeholder for always-ready clocks
subscription_hook.h	SubscriptionHook<Tag, E> extension point for PTP callbacks
availability_hook.h	AvailabilityHook<Tag> extension point for async readiness

New clock domains

Package	Bazel target	Description
score/time/vehicle_time/	:vehicle_time / :vehicle_time_mock / :interface	PTP-synchronized vehicle time
score/time/hpls_time/	:hpls_time / :hpls_time_mock / :interface	High-Precision Local Steady Clock
score/time/steady_time/	:steady_time / :steady_time_mock / :interface	std::chrono::steady_clock wrapper
score/time/system_time/	:system_time / :system_time_mock / :interface	std::chrono::system_clock wrapper
score/time/ptp/	:ptp_types	TimeSlaveSyncData<Tag>, PDelayMeasurementData<Tag>

Visibility hardening

• Internal targets (*_clock, *_clock_iface, *_clock_impl, *_clock_mock,
  clock_core) restricted to //score/time:__subpackages__.
• Three named public aliases per domain: :vehicle_time (prod), :vehicle_time_mock
  (test), :interface (header-only).
• examples/time/ aggregation moved to its own //examples/time:unit_test_suite; no longer
  referenced from //score/time:unit_test_suite.

Examples — examples/time/

Four self-contained examples (one per domain) demonstrating polling, status checks, and
callback registration. Handler filenames match class names
(vehicle_time_handler.h / VehicleTimeHandler, etc.).

Legacy deprecation

score/time/SynchronizedVehicleTime/BUILD and score/time/HighPrecisionLocalSteadyClock/BUILD
retain a DEPRECATED comment block and carry deprecation = "..." on their alias targets
so any target that still depends on them receives a Bazel analysis-time warning. Both packages
are kept until score/TimeDaemon/ consumers complete migration.

Documentation — docs/time/

New Sphinx RST documentation for the score::time API, with six use-case sections and five
PlantUML sequence/class diagrams. The former docs/time/ (TimeDaemon architecture) is
renamed to docs/TimeDaemon/.

---

API example

// Production code — no factory, no constructor injection
auto clock = score::time::VehicleClock::GetInstance();
if (clock.IsAvailable()) {
    auto snap = clock.Now();
    if (snap.Status().IsSynchronized()) {
        UseTime(snap.TimePoint());
    }
}

// Unit test — RAII mock injection, SUT unchanged
auto mock = std::make_shared<score::time::VehicleTimeMock>();
score::time::ClockOverrideGuard<score::time::VehicleTime> guard{mock};
EXPECT_CALL(*mock, Now()).WillOnce(Return(snapshot));
MySvc svc{};  // calls GetInstance() internally — gets mock

[github-actions]

License Check Results

🚀 The license check job ran with the Bazel command:

bazel run //:license-check

Status: ⚠️ Needs Review

Click to expand output

[License Check Output]
2026/05/02 20:43:23 Downloading https://releases.bazel.build/8.3.0/release/bazel-8.3.0-linux-x86_64...
Extracting Bazel installation...
Starting local Bazel server (8.3.0) and connecting to it...
INFO: Invocation ID: c452ad9e-ba85-4240-af45-a0530ba63e71
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
WARNING: For repository 'aspect_rules_lint', the root module requires module version aspect_rules_lint@1.5.3, but got aspect_rules_lint@2.0.0 in the resolved dependency graph. Please update the version in your MODULE.bazel or set --check_direct_dependencies=off
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Loading: 
Loading: 2 packages loaded
Loading: 2 packages loaded
    currently loading: 
Loading: 2 packages loaded
    currently loading: 
Loading: 2 packages loaded
    currently loading: 
Loading: 2 packages loaded
    currently loading: 
Loading: 2 packages loaded
    currently loading: 
Loading: 2 packages loaded
    currently loading: 
Loading: 2 packages loaded
    currently loading: 
WARNING: Download from https://github.com/aspect-build/rules_lint/releases/download/v2.0.0/rules_lint-v2.0.0.tar.gz failed: class java.io.IOException GET returned 502 Bad Gateway or Proxy Error
INFO: Repository aspect_rules_lint+ instantiated at:
  <builtin>: in <toplevel>
Repository rule http_archive defined at:
  /home/runner/.bazel/external/bazel_tools/tools/build_defs/repo/http.bzl:394:31: in <toplevel>
ERROR: /home/runner/.bazel/external/bazel_tools/tools/build_defs/repo/http.bzl:139:45: An error occurred during the fetch of repository 'aspect_rules_lint+':
   Traceback (most recent call last):
	File "/home/runner/.bazel/external/bazel_tools/tools/build_defs/repo/http.bzl", line 139, column 45, in _http_archive_impl
		download_info = ctx.download_and_extract(
Error in download_and_extract: java.io.IOException: Error downloading [https://github.com/aspect-build/rules_lint/releases/download/v2.0.0/rules_lint-v2.0.0.tar.gz] to /home/runner/.bazel/external/aspect_rules_lint+/temp15498933779504688265/rules_lint-v2.0.0.tar.gz: GET returned 502 Bad Gateway or Proxy Error
WARNING: Target pattern parsing failed.
ERROR: Skipping '//:license-check': no such package '@@aspect_rules_lint+//format': java.io.IOException: Error downloading [https://github.com/aspect-build/rules_lint/releases/download/v2.0.0/rules_lint-v2.0.0.tar.gz] to /home/runner/.bazel/external/aspect_rules_lint+/temp15498933779504688265/rules_lint-v2.0.0.tar.gz: GET returned 502 Bad Gateway or Proxy Error
ERROR: no such package '@@aspect_rules_lint+//format': java.io.IOException: Error downloading [https://github.com/aspect-build/rules_lint/releases/download/v2.0.0/rules_lint-v2.0.0.tar.gz] to /home/runner/.bazel/external/aspect_rules_lint+/temp15498933779504688265/rules_lint-v2.0.0.tar.gz: GET returned 502 Bad Gateway or Proxy Error
INFO: Elapsed time: 35.201s
INFO: 0 processes.
ERROR: Build did NOT complete successfully
ERROR: Build failed. Not running target

[github-actions]

The created documentation from the pull request is available at: docu-html