feat: rename Clock service to CarbonClock and introduce CarbonClockInterface for improved type safety

Author: Neunerlei

_changelog/next.md

@@ -139,6 +139,7 @@
 - `ApiDataScopeContextSettingMiddleware` lets API clients opt out of specific contextual scopes per request via the `?no_scope[resource]=*` query parameter, providing escape hatches for admin queries that need unfiltered data.
 - The `AiService` facade has been expanded with: `getAgent(name)`, `tryToGetAgent(name)`, `getMcpClient(server)`, `getSystemPrompts()`, `getSystemModels()` — making it the single entry point for all AI-related service resolution.
 - Background queue workers now run with `--timeout=0` (no per-job timeout), preventing long-running AI streaming jobs from being killed mid-response.
+- The `Clock` service has been renamed to `CarbonClock` and a new `CarbonClockInterface` (extending `Psr\Clock\ClockInterface`) has been introduced. The interface guarantees `CarbonImmutable` as the return type of `now()`, improving type safety across all time-dependent services. Both `ClockInterface` and `CarbonClockInterface` resolve to the same singleton in the service container. All internal services (caching, crypto, URL signing, file converters, frontend migrations) now use constructor injection of this clock, making time-dependent logic fully testable.
 
 ### Deprecation
 

_docker_production/docker-compose.yml

@@ -157,7 +157,7 @@ services:
             nofile:
                 soft: 65536
                 hard: 65536
-        restart: no
+        restart: always
         volumes:
             - mysql_data:/var/lib/mysql
         ports:

_documentation/400-Contributing.md

@@ -120,7 +120,7 @@ Before submitting your PR:
 - [ ] Value objects are `readonly` with `from...` / `tryFrom...` factory methods
 - [ ] Enums used for all constrained string or int values
 - [ ] DocBlocks only where needed (complex types, non-obvious intent)
-- [ ] No `now()`, `new \DateTime()`, `Carbon::now()`, or similar — use injected `Psr\Clock\ClockInterface`
+- [ ] No `now()`, `new \DateTime()`, `Carbon::now()`, or similar — use injected `CarbonClockInterface` (`Psr\Clock\ClockInterface` if the class must stay PSR-only)
 - [ ] No debug statements (`dd()`, `dump()`, `var_dump()`)
 - [ ] No hardcoded values (use config or constants)
 - [ ] You provided good test coverage for new features and bug fixes

_documentation/500-Backend/100-Architecture/index.md

@@ -74,7 +74,7 @@ readonly class AiService
         #[Config('hawki.aiHandle')]
         private string $aiHandle,
         private Psr\Log\LoggerInterface $logger,
-        private Psr\Clock\ClockInterface $clock,
+        private App\Services\System\Time\CarbonClockInterface $clock,
     ) {}
 }
 ```
@@ -86,10 +86,12 @@ readonly class AiService
 | Config value | `#[Config('section.key')] string $value`                |
 | Cache        | `#[Cache] Illuminate\Contracts\Cache\Repository $cache` |
 | Logging      | `Psr\Log\LoggerInterface $logger`                       |
-| Current time | `Psr\Clock\ClockInterface $clock`                       |
+| Current time | `App\Services\System\Time\CarbonClockInterface $clock`  |
 
 `now()`, `Carbon::now()`, and `new \DateTime()` are banned in services, repositories, and value objects. They make time non-deterministic in tests.
 
+`CarbonClockInterface` extends the PSR-20 `Psr\Clock\ClockInterface` but types `now()` to return `CarbonImmutable` instead of a plain `DateTimeImmutable`, so services get Carbon's API without an extra cast. Both interfaces are bound to the same `CarbonClock` singleton (see `AppServiceProvider::registerClockForInterface()`); inject `Psr\Clock\ClockInterface` instead only when a class needs to stay framework/PSR-agnostic (e.g. shared library code).
+
 ## ServiceLocatorTrait (API Resources only)
 
 `ServiceLocatorTrait` (`App\Services\System\Container\ServiceLocatorTrait`) exists because Laravel's JSON:API library instantiates `JsonApiResource` subclasses outside the container's constructor chain. Constructor injection is not available there.

_documentation/500-Backend/1000-Infrastructure/300-Announcements.md

@@ -9,7 +9,7 @@ control.
 `Session::put()` (session access from a service), and `now()` (direct time construction) — all
 of which violate HAWKI's coding standards for services. This is a confirmed deviation tracked
 in the [Technical Debt Register](../100-Architecture/300-Technical-Debt.md). Do not copy these
-patterns; follow the standard (constructor-injected `ClockInterface`, no facades in services,
+patterns; follow the standard (constructor-injected `CarbonClockInterface`, no facades in services,
 no session access) in any new code you write in this area.
 :::
 

app/Providers/AppServiceProvider.php

@@ -13,7 +13,8 @@
 use App\Services\System\Http\Exceptions\SsrfBlockedException;
 use App\Services\System\Http\SsrfSafeGetterMacro;
 use App\Services\System\ScheduleWithDynamicIntervalFactory;
-use App\Services\System\Time\Clock;
+use App\Services\System\Time\CarbonClock;
+use App\Services\System\Time\CarbonClockInterface;
 use App\Services\System\UsageTypes\UsageContext;
 use App\Services\System\UserTypes\UserContext;
 use App\Services\Translation\LocaleService;
@@ -208,6 +209,7 @@ private function registerDisablingGlobalScopesForEloquentUserProvider(): void
 
     private function registerClockForInterface(): void
     {
-        $this->app->singleton(ClockInterface::class, static fn() => new Clock());
+        $this->app->singleton(ClockInterface::class, static fn() => new CarbonClock());
+        $this->app->singleton(CarbonClockInterface::class, static fn() => new CarbonClock());
     }
 }

app/Services/Ai/ModelInformation/Enrichment/Implementations/LiteLlm/LiteLlmApiDataStore.php

@@ -6,7 +6,7 @@
 
 
 use App\Services\Ai\Providers\Values\AiProviderProxy;
-use App\Services\System\Time\Clock;
+use App\Services\System\Time\CarbonClock;
 use Illuminate\Contracts\Cache\Repository;
 use Psr\Log\LoggerInterface;
 
@@ -18,11 +18,11 @@
 class LiteLlmApiDataStore extends AbstractLiteLlmDataStore
 {
     public function __construct(
-        private readonly LiteLlmApiClient             $apiClient,
-        private readonly Repository                   $cache,
+        private readonly LiteLlmApiClient    $apiClient,
+        private readonly Repository          $cache,
         LoggerInterface                      $logger,
         LiteLlmDriverNameProviderNameMapping $nameMapping,
-        private readonly Clock                        $clock = new Clock()
+        private readonly CarbonClock         $clock = new CarbonClock()
     )
     {
         parent::__construct($logger, $nameMapping);

app/Services/Ai/Tools/Implementations/TestTool.php

@@ -4,9 +4,8 @@
 namespace App\Services\Ai\Tools\Implementations;
 
 use App\Services\Ai\Tools\AbstractTool;
-use Carbon\Carbon;
+use App\Services\System\Time\CarbonClockInterface;
 use Illuminate\Contracts\JsonSchema\JsonSchema;
-use Psr\Clock\ClockInterface;
 use Psr\Log\LoggerInterface;
 
 /**
@@ -55,9 +54,9 @@ public function schema(JsonSchema $schema): array
     }
 
     public function __invoke(
-        ClockInterface $clock,
-        string         $message,
-        int            $count = 1,
+        CarbonClockInterface $clock,
+        string               $message,
+        int                  $count = 1,
     ): array
     {
         $this->logger->info('TestTool executed', [
@@ -73,7 +72,7 @@ public function __invoke(
             'instruction' => 'Now greet the user and let them know the tool test was successful. Do not call this tool again.',
             'original_message' => $message,
             'count' => $count,
-            'timestamp' => (new Carbon($clock->now()))->toIso8601String()
+            'timestamp' => $clock->now()->toIso8601String()
         ];
     }
 }

app/Services/ExtApp/ConnectRequestCrypto.php

@@ -8,7 +8,7 @@
 use App\Services\ExtApp\Config\ExtAppConfig;
 use App\Services\ExtApp\Repositories\ExtAppRepository;
 use App\Services\Frontend\Connection\Values\ExtAppConnectRequestPayload;
-use App\Services\System\Time\Clock;
+use App\Services\System\Time\CarbonClock;
 use Carbon\Carbon;
 use Hawk\HawkiCrypto\SymmetricCrypto;
 use Hawk\HawkiCrypto\Value\SymmetricCryptoValue;
@@ -27,7 +27,7 @@ public function __construct(
         private ExtAppConfig     $config,
         private SymmetricCrypto  $crypto,
         private ExtAppRepository $extAppRepository,
-        private Clock            $clock = new Clock()
+        private CarbonClock      $clock = new CarbonClock()
     )
     {
     }

app/Services/ExtApp/ExtAppUrlBuilder.php

@@ -7,7 +7,7 @@
 
 use App\Models\ExtApp;
 use App\Services\ExtApp\Config\ExtAppConfig;
-use App\Services\System\Time\Clock;
+use App\Services\System\Time\CarbonClock;
 use GuzzleHttp\Psr7\Uri;
 use Illuminate\Contracts\Routing\UrlGenerator;
 
@@ -20,7 +20,7 @@
     public function __construct(
         private UrlGenerator $urlGenerator,
         private ExtAppConfig $config,
-        private Clock        $clock = new Clock(),
+        private CarbonClock  $clock = new CarbonClock(),
     )
     {
     }