feat(core): add system store service interface

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

shared/lib/SystemStore/BlobInfo.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXF\SystemStore;
+
+use DateTimeImmutable;
+use InvalidArgumentException;
+
+/**
+ * Provider-neutral information about a blob in a system store.
+ */
+final readonly class BlobInfo
+{
+    public function __construct(
+        public string $key,
+        public string $mimeType,
+        public int $size,
+        public string $etag,
+        public DateTimeImmutable $modifiedAt,
+        public array $attributes = [],
+    ) {
+        if ($this->key === '') {
+            throw new InvalidArgumentException('Blob key cannot be empty');
+        }
+
+        if ($this->mimeType === '') {
+            throw new InvalidArgumentException('Blob MIME type cannot be empty');
+        }
+
+        if ($this->size < 0) {
+            throw new InvalidArgumentException('Blob size cannot be negative');
+        }
+
+        if ($this->etag === '') {
+            throw new InvalidArgumentException('Blob ETag cannot be empty');
+        }
+    }
+
+}

shared/lib/SystemStore/Provider/ProviderBaseInterface.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXF\SystemStore\Provider;
+
+use KTXF\Resource\Provider\ResourceProviderBaseInterface;
+
+/**
+ * Provider for tenant-scoped internal storage services.
+ */
+interface ProviderBaseInterface extends ResourceProviderBaseInterface
+{
+    public const JSON_TYPE = 'system-store:provider';
+}

shared/lib/SystemStore/Service/SystemStoreServiceInterface.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXF\SystemStore\Service;
+
+use KTXF\Resource\BinaryResource;
+use KTXF\Resource\Provider\ResourceServiceBaseInterface;
+use KTXF\SystemStore\BlobInfo;
+use KTXF\SystemStore\WriteCondition;
+
+/**
+ * Basic key-addressed storage contract for tenant-owned system data.
+ */
+interface SystemStoreServiceInterface extends ResourceServiceBaseInterface
+{
+    public const JSON_TYPE = 'system-store:service';
+
+    public function stat(string $key): ?BlobInfo;
+
+    public function read(string $key): ?BinaryResource;
+
+    public function write(
+        string $key,
+        BinaryResource $content,
+        array $metadata = [],
+        ?WriteCondition $condition = null,
+    ): BlobInfo;
+
+    public function delete(
+        string $key,
+        ?WriteCondition $condition = null,
+    ): bool;
+
+    /**
+     * Iterates stored metadata lazily. Implementations must keep memory use
+     * bounded and handle any backend pagination internally.
+     *
+     * @return iterable<BlobInfo>
+     */
+    public function list(string $prefix = ''): iterable;
+}

shared/lib/SystemStore/WriteCondition.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXF\SystemStore;
+
+use InvalidArgumentException;
+
+/**
+ * Optional precondition applied atomically by a system-store write or delete.
+ */
+final readonly class WriteCondition
+{
+    public const NONE = 'none';
+    public const IF_ABSENT = 'if-absent';
+    public const IF_MATCH = 'if-match';
+
+    private function __construct(
+        public string $mode,
+        public ?string $etag = null,
+    ) {
+        if (!in_array($this->mode, [self::NONE, self::IF_ABSENT, self::IF_MATCH], true)) {
+            throw new InvalidArgumentException('Invalid system-store write condition: ' . $this->mode);
+        }
+
+        if ($this->mode === self::IF_MATCH && ($this->etag === null || $this->etag === '')) {
+            throw new InvalidArgumentException('An ETag is required for an if-match condition');
+        }
+
+        if ($this->mode !== self::IF_MATCH && $this->etag !== null) {
+            throw new InvalidArgumentException('An ETag is only valid for an if-match condition');
+        }
+    }
+
+    public static function none(): self
+    {
+        return new self(self::NONE);
+    }
+
+    public static function ifAbsent(): self
+    {
+        return new self(self::IF_ABSENT);
+    }
+
+    public static function ifMatch(string $etag): self
+    {
+        return new self(self::IF_MATCH, $etag);
+    }
+}