feat(core): add system store service interface

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

shared/lib/Resource/Provider/ProviderInterface.php

@@ -15,6 +15,7 @@ interface ProviderInterface
     public const TYPE_PEOPLE = 'people';
     public const TYPE_CHRONO = 'chrono';
     public const TYPE_MAIL = 'mail';
+    public const TYPE_SYSTEM_STORE = 'system-store';
 
     /**
      * Provider type (e.g., 'authentication', 'document', 'people', 'chrono', 'mail')

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);
+    }
+}

tests/php/Unit/SystemStore/SystemStoreContractsTest.php

@@ -0,0 +1,83 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXT\Unit\SystemStore;
+
+use DateTimeImmutable;
+use InvalidArgumentException;
+use KTXF\Resource\Provider\ProviderInterface;
+use KTXF\Resource\Provider\ResourceProviderBaseInterface;
+use KTXF\Resource\Provider\ResourceServiceBaseInterface;
+use KTXF\SystemStore\BlobInfo;
+use KTXF\SystemStore\Provider\ProviderBaseInterface;
+use KTXF\SystemStore\Service\SystemStoreServiceInterface;
+use KTXF\SystemStore\WriteCondition;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use ReflectionClass;
+
+final class SystemStoreContractsTest extends TestCase
+{
+    #[Test]
+    public function registersTheSystemStoreProviderType(): void
+    {
+        self::assertSame('system-store', ProviderInterface::TYPE_SYSTEM_STORE);
+    }
+
+    #[Test]
+    public function providerAndServiceContractsExtendResourceContracts(): void
+    {
+        self::assertTrue((new ReflectionClass(ProviderBaseInterface::class))->isSubclassOf(ResourceProviderBaseInterface::class));
+        self::assertTrue((new ReflectionClass(SystemStoreServiceInterface::class))->isSubclassOf(ResourceServiceBaseInterface::class));
+    }
+
+    #[Test]
+    public function listingIsAProviderPaginatedIterable(): void
+    {
+        $method = (new ReflectionClass(SystemStoreServiceInterface::class))->getMethod('list');
+
+        self::assertSame('iterable', (string) $method->getReturnType());
+        self::assertCount(1, $method->getParameters());
+    }
+
+    #[Test]
+    public function createsSupportedWriteConditions(): void
+    {
+        self::assertSame(WriteCondition::NONE, WriteCondition::none()->mode);
+        self::assertSame(WriteCondition::IF_ABSENT, WriteCondition::ifAbsent()->mode);
+
+        $condition = WriteCondition::ifMatch('revision-1');
+        self::assertSame(WriteCondition::IF_MATCH, $condition->mode);
+        self::assertSame('revision-1', $condition->etag);
+    }
+
+    #[Test]
+    public function rejectsAnEmptyIfMatchEtag(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        WriteCondition::ifMatch('');
+    }
+
+    #[Test]
+    public function serializesMetadata(): void
+    {
+        $metadata = new BlobInfo(
+            key: 'previews/example.webp',
+            mimeType: 'image/webp',
+            size: 123,
+            etag: 'revision-1',
+            modifiedAt: new DateTimeImmutable('2026-08-28T12:00:00+00:00'),
+            attributes: ['variant' => 'popover'],
+        );
+
+        self::assertSame([
+            'key' => 'previews/example.webp',
+            'mime' => 'image/webp',
+            'size' => 123,
+            'etag' => 'revision-1',
+            'modifiedAt' => '2026-08-28T12:00:00+00:00',
+            'attributes' => ['variant' => 'popover'],
+        ], $metadata->jsonSerialize());
+    }
+}