feat: implement meta and content cache

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

lib/Providers/EntityResource.php

@@ -18,6 +18,9 @@ use KTXF\Mail\Object\MessagePropertiesMutableInterface;
  */
 class EntityResource extends EntityMutableAbstract {
 
+    /** Version of the meta store / content store formats; bump on any change to either */
+    public const CACHE_SCHEMA_VERSION = 1;
+
     public function __construct(
         string $provider = 'imap',
         string|int|null $service = null,
@@ -63,6 +66,69 @@ class EntityResource extends EntityMutableAbstract {
         return $this;
     }
 
+    // ── Cache (meta store / content store) ───────────────────────────────────
+
+    /**
+     * Serialise to a meta store document.
+     *
+     * The store adds the key fields it owns (sid, tid, uidValidity).
+     */
+    public function toCacheMeta(): array
+    {
+        return [
+            'mailbox'       => (string) $this->data['collection'],
+            'uid'           => (int) $this->data['identifier'],
+            'created'       => $this->data['created'] ?? null,
+            'schemaVersion' => self::CACHE_SCHEMA_VERSION,
+            ...$this->getProperties()->toCacheMeta(),
+        ];
+    }
+
+    /**
+     * Restore identity and mutable fields (flags) from a meta store document.
+     */
+    public function fromCacheMeta(array $document): static
+    {
+        $this->data['collection'] = (string) $document['mailbox'];
+        $this->data['identifier'] = (int) $document['uid'];
+
+        $this->getProperties()->fromCacheMeta($document);
+
+        return $this;
+    }
+
+    /**
+     * Serialise the immutable message content for the content store (message.json).
+     */
+    public function toCacheContent(): array
+    {
+        return [
+            'schemaVersion' => self::CACHE_SCHEMA_VERSION,
+            'created'       => $this->data['created'] ?? null,
+            'properties'    => $this->getProperties()->toCacheContent(),
+        ];
+    }
+
+    /**
+     * Restore the immutable message content from the content store (message.json).
+     *
+     * @throws \UnexpectedValueException when the content was written with a different schema version
+     */
+    public function fromCacheContent(array $content): static
+    {
+        if (($content['schemaVersion'] ?? null) !== self::CACHE_SCHEMA_VERSION) {
+            throw new \UnexpectedValueException('Cached message content has an unsupported schema version');
+        }
+
+        if (isset($content['created'])) {
+            $this->data['created'] = $content['created'];
+        }
+
+        $this->getProperties()->fromCacheContent($content['properties'] ?? []);
+
+        return $this;
+    }
+
     /**
      * @inheritDoc
      */