feat(core): add system store service interface

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

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