feat(core): add tenant system store contracts and configuration

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>

shared/lib/SystemStore/StoreReference.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXF\SystemStore;
+
+use InvalidArgumentException;
+
+/**
+ * Provider and service selected for one logical tenant system store.
+ */
+final readonly class StoreReference
+{
+    public function __construct(
+        public string $provider,
+        public string|int $service,
+        public string $namespace,
+    ) {
+        if ($this->provider === '') {
+            throw new InvalidArgumentException('System-store provider cannot be empty');
+        }
+
+        if ($this->service === '') {
+            throw new InvalidArgumentException('System-store service cannot be empty');
+        }
+
+        if ($this->namespace === '') {
+            throw new InvalidArgumentException('System-store namespace cannot be empty');
+        }
+    }
+
+    public static function fromArray(array $data): self
+    {
+        $provider = $data['provider'] ?? null;
+        $service = $data['service'] ?? null;
+        $namespace = $data['namespace'] ?? null;
+
+        if (!is_string($provider) || (!is_string($service) && !is_int($service)) || !is_string($namespace)) {
+            throw new InvalidArgumentException('Invalid system-store reference');
+        }
+
+        return new self($provider, $service, $namespace);
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'provider' => $this->provider,
+            'service' => $this->service,
+            'namespace' => $this->namespace,
+        ];
+    }
+}

shared/lib/SystemStore/SystemStoreManagerInterface.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXF\SystemStore;
+
+use KTXF\Resource\BinaryResource;
+
+/**
+ * Tenant-scoped access to logical internal stores.
+ */
+interface SystemStoreManagerInterface
+{
+    public function stat(string $tenantId, string $store, string $key): ?BlobInfo;
+
+    public function read(string $tenantId, string $store, string $key): ?BinaryResource;
+
+    public function write(
+        string $tenantId,
+        string $store,
+        string $key,
+        BinaryResource $content,
+        array $metadata = [],
+        ?WriteCondition $condition = null,
+    ): BlobInfo;
+
+    public function delete(
+        string $tenantId,
+        string $store,
+        string $key,
+        ?WriteCondition $condition = null,
+    ): bool;
+
+    /**
+     * @return iterable<BlobInfo>
+     */
+    public function list(string $tenantId, string $store, string $prefix = ''): iterable;
+}