fix(deps): update dependency vue-router to v5

.github/workflows/php-integration-tests.yml

@@ -1,59 +0,0 @@
-name: PHP Integration Tests
-
-on:
-  pull_request:
-  workflow_dispatch:
-
-jobs:
-  test:
-    name: Integration Tests
-    runs-on: ubuntu-latest
-    services:
-      mongo:
-        image: mongo:8
-        options: >-
-          --health-cmd "mongosh --quiet --eval \"db.adminCommand('ping')\""
-          --health-interval 5s
-          --health-timeout 5s
-          --health-retries 12
-
-    steps:
-      - name: Retrieve Server Install Action
-        uses: actions/checkout@v6.0.2
-        with:
-          repository: Nodarx/action-server-install
-          ref: main
-          path: action-server-install
-          github-server-url: https://git.ktrix.dev
-
-      - name: Install server
-        uses: ./action-server-install
-        with:
-          install-php: 'true'
-          php-version: '8.5'
-          server-path: './server'
-          database-uri: 'mongodb://mongo:27017/?tls=false'
-          database-name: 'ktrix_ci'
-          app-environment: 'test'
-
-      - name: Checkout module under test
-        uses: actions/checkout@v6.0.2
-        with:
-          repository: ${{ github.repository }}
-          ref: ${{ github.event.pull_request.head.sha || github.sha }}
-          path: server/modules/mail_manager
-          github-server-url: https://git.ktrix.dev
-
-      - name: Install module dependencies
-        run: composer install --prefer-dist --no-progress
-        working-directory: server/modules/mail_manager
-
-      - name: Install and enable module
-        working-directory: server
-        run: |
-          php bin/console module:install mail_manager
-          php bin/console module:enable mail_manager
-
-      - name: Run integration tests
-        working-directory: server/modules/mail_manager
-        run: composer test:integration

.github/workflows/renovate.yml

@@ -25,17 +25,11 @@ jobs:
           tools: composer:v2
 
       - name: Install Renovate
-        run: |
-          npm install --global --no-audit --fund=false \
-            --prefix "${{ runner.temp }}/renovate-npm" \
-            --cache "${{ runner.temp }}/renovate-npm-cache" \
-            renovate
-          "${{ runner.temp }}/renovate-npm/bin/renovate" --version
+        run: npm install -g renovate
 
       - name: Run Renovate
         env:
           RENOVATE_TOKEN: ${{ secrets.RENOVATE_TOKEN }}
           RENOVATE_PLATFORM: gitea
           RENOVATE_ENDPOINT: https://git.ktrix.dev/api/v1
-        run: |
-          "${{ runner.temp }}/renovate-npm/bin/renovate" ${{ gitea.repository }}
+        run: renovate ${{ gitea.repository }}

.gitignore

@@ -14,7 +14,11 @@ node_modules/
 # Backend development
 /lib/vendor/
 coverage/
-*.cache
+phpunit.xml.cache
+.phpunit.cache
+.phpunit.result.cache
+.php-cs-fixer.cache
+.phpstan.cache
 .phpactor/
 
 # Editors

composer.json

@@ -10,16 +10,16 @@
   "config": {
     "optimize-autoloader": true,
     "platform": {
-      "php": "8.3"
+      "php": "8.2"
     },
     "autoloader-suffix": "MailManager",
     "vendor-dir": "lib/vendor"
   },
   "require": {
-    "php": ">=8.3 <=8.5"
+    "php": ">=8.2 <=8.5"
   },
   "require-dev": {
-    "phpunit/phpunit": "^12.0"
+    "phpunit/phpunit": "^11.0"
   },
   "autoload": {
     "psr-4": {
@@ -36,8 +36,7 @@
       ],
       "post-update-cmd": [
       ],
-      "test:unit": "phpunit --configuration tests/php/phpunit.xml --testsuite \"Unit Tests\" --colors=always --testdox",
-      "test:integration": "phpunit --configuration tests/php/phpunit.xml --testsuite \"Integration Tests\" --colors=always --testdox",
-      "test:coverage": "XDEBUG_MODE=coverage phpunit --configuration tests/php/phpunit.xml --testsuite \"Unit Tests\" --coverage-html .phpunit.coverage --coverage-text"
+      "test:unit": "phpunit --configuration tests/php/phpunit.unit.xml --colors=always --testdox",
+      "test:coverage": "XDEBUG_MODE=coverage phpunit --configuration tests/php/phpunit.unit.xml --coverage-html .phpunit.coverage --coverage-text"
   }
 }

lib/Controllers/DefaultController.php

@@ -13,9 +13,8 @@ use InvalidArgumentException;
 use KTXC\Http\Response\JsonResponse;
 use KTXC\Http\Response\Response;
 use KTXC\Http\Response\StreamedNdJsonResponse;
-use KTXC\Http\Response\StreamedResponse;
-use KTXC\Context\IdentityContextInterface;
-use KTXC\Context\TenantContextInterface;
+use KTXC\SessionIdentity;
+use KTXC\SessionTenant;
 use KTXF\Controller\ControllerAbstract;
 use KTXF\Json\JsonSerializable;
 use KTXF\Resource\Identifier\CollectionIdentifier;
@@ -24,12 +23,20 @@ use KTXF\Resource\Identifier\ResourceIdentifier;
 use KTXF\Resource\Identifier\ResourceIdentifiers;
 use KTXF\Resource\Identifier\ServiceIdentifier;
 use KTXF\Resource\Provider\ResourceServiceLocationInterface;
-use KTXF\Resource\SystemIdentity;
+use KTXF\Resource\Selector\CollectionSelector;
+use KTXF\Resource\Selector\ServiceSelector;
+use KTXF\Resource\Selector\SourceSelector;
 use KTXF\Routing\Attributes\AuthenticatedRoute;
 use KTXM\MailManager\Manager;
 use Psr\Log\LoggerInterface;
 use Throwable;
 
+/**
+ * Default Controller - Unified Mail API
+ * 
+ * Handles all mail operations in JMAP-style API pattern.
+ * Supports both single operations and batches with result references.
+ */
 class DefaultController extends ControllerAbstract {
 
     private const ERR_MISSING_PROVIDER = 'Missing parameter: provider';
@@ -39,7 +46,6 @@ class DefaultController extends ControllerAbstract {
     private const ERR_MISSING_SOURCES = 'Missing parameter: sources';
     private const ERR_MISSING_TARGET = 'Missing parameter: target';
     private const ERR_MISSING_TARGETS = 'Missing parameter: targets';
-    private const ERR_MISSING_SENDER = 'Missing parameter: sender';
     private const ERR_INVALID_OPERATION = 'Invalid operation: ';
     private const ERR_INVALID_PROVIDER = 'Invalid parameter: provider must be a string';
     private const ERR_INVALID_SERVICE = 'Invalid parameter: service must be a string';
@@ -47,13 +53,14 @@ class DefaultController extends ControllerAbstract {
     private const ERR_INVALID_SOURCES = 'Invalid parameter: sources must be an array';
     private const ERR_INVALID_TARGET = 'Invalid parameter: target must be an array';
     private const ERR_INVALID_TARGETS = 'Invalid parameter: targets must be an array';
-    private const ERR_INVALID_SENDER = 'Invalid parameter: sender must be a string';
     private const ERR_INVALID_DATA = 'Invalid parameter: data must be an array';
 
+    private const STREAM_FLUSH_INTERVAL = 1;
+
     public function __construct(
-        private readonly TenantContextInterface $tenantContext,
-        private readonly IdentityContextInterface $identityContext,
-        private Manager $manager,
+        private readonly SessionTenant $tenantIdentity,
+        private readonly SessionIdentity $userIdentity,
+        private Manager $mailManager,
         private readonly LoggerInterface $logger
     ) {}
     
@@ -80,26 +87,8 @@ class DefaultController extends ControllerAbstract {
     ): Response {
 
         // authorize request
-        $tenantId = $this->tenantContext->identifier();
-        $userId = $this->identityContext->identifier();
-
-        // acting-user override: only the reserved system context is permitted,
-        // gated on the system mail management permission
-        if ($user !== null && $user !== $userId) {
-            if ($user !== SystemIdentity::USER || !$this->identityContext->hasPermission('mail_manager.system')) {
-                return new JsonResponse([
-                    'version' => $version,
-                    'transaction' => $transaction,
-                    'operation' => $operation,
-                    'status' => 'error',
-                    'data' => [
-                        'code' => JsonResponse::HTTP_FORBIDDEN,
-                        'message' => 'Not permitted to act as user: ' . $user
-                    ]
-                ], JsonResponse::HTTP_FORBIDDEN);
-            }
-            $userId = $user;
-        }
+        $tenantId = $this->tenantIdentity->identifier();
+        $userId = $this->userIdentity->identifier();
 
         try {
             
@@ -172,16 +161,13 @@ class DefaultController extends ControllerAbstract {
             'entity.fetch' => $this->entityFetch($tenantId, $userId, $data),
             'entity.extant' => $this->entityExtant($tenantId, $userId, $data),
             'entity.delta' => $this->entityDelta($tenantId, $userId, $data),
-            'entity.create' => $this->entityCreate($tenantId, $userId, $data),
-            'entity.update' => $this->entityUpdate($tenantId, $userId, $data),
+            'entity.create' => throw new InvalidArgumentException('Operation not implemented: ' . $operation),
+            'entity.update' => throw new InvalidArgumentException('Operation not implemented: ' . $operation),
             'entity.delete' => $this->entityDelete($tenantId, $userId, $data),
             'entity.patch' => $this->entityPatch($tenantId, $userId, $data),
             'entity.move' => $this->entityMove($tenantId, $userId, $data),
             'entity.copy' => throw new InvalidArgumentException('Operation not implemented: ' . $operation),
-            'entity.submit' => $this->entitySubmit($tenantId, $userId, $data),
-            'entity.download' => $this->entityDownload($tenantId, $userId, $data),
-            'entity.preview' => $this->entityPreview($tenantId, $userId, $data),
-            'entity.blobs' => $this->entityBlobs($tenantId, $userId, $data),
+            'entity.transmit' => $this->entityTransmit($tenantId, $userId, $data),
             
             default => throw new InvalidArgumentException(self::ERR_INVALID_OPERATION . $operation)
         };
@@ -191,48 +177,40 @@ class DefaultController extends ControllerAbstract {
 
     private function providerList(string $tenantId, string $userId, array $data): mixed {
 
-        if (isset($data['targets'])) {
-            if (!is_array($data['targets'])) {
-                throw new InvalidArgumentException(self::ERR_INVALID_TARGETS);
-            }
+        $sources = null;
+		if (isset($data['sources']) && is_array($data['sources'])) {
+			$sources = new SourceSelector();
+			$sources->jsonDeserialize($data['sources']);
+		}
 		
-            foreach ($data['targets'] as $target) {
-                if (!is_string($target)) {
-                    throw new InvalidArgumentException(self::ERR_INVALID_TARGETS);
-                }
-            }
-        }
-		
-		return $this->manager->providerList($tenantId, $userId, $data['targets'] ?? []);
+		return $this->mailManager->providerList($tenantId, $userId, $sources);
 
     }
 
     private function providerFetch(string $tenantId, string $userId, array $data): mixed {
         
-        if (!isset($data['target'])) {
-            throw new InvalidArgumentException(self::ERR_MISSING_TARGET);
+        if (!isset($data['identifier'])) {
+            throw new InvalidArgumentException(self::ERR_MISSING_IDENTIFIER);
         }
-        if (!is_string($data['target'])) {
-            throw new InvalidArgumentException(self::ERR_INVALID_TARGET);
+        if (!is_string($data['identifier'])) {
+            throw new InvalidArgumentException(self::ERR_INVALID_IDENTIFIER);
         }
         
-        return $this->manager->providerFetch($tenantId, $userId, $data['target']);
-
+        return $this->mailManager->providerFetch($tenantId, $userId, $data['identifier']);
     }
 
     private function providerExtant(string $tenantId, string $userId, array $data): mixed {
         
-        if (!isset($data['targets'])) {
-            throw new InvalidArgumentException(self::ERR_MISSING_TARGETS);
-        }
+        if (!isset($data['sources'])) {
+			throw new InvalidArgumentException(self::ERR_MISSING_SOURCES);
+		}
+		if (!is_array($data['sources'])) {
+			throw new InvalidArgumentException(self::ERR_INVALID_SOURCES);	
+		}
+		$sources = new SourceSelector();
+		$sources->jsonDeserialize($data['sources']);
 		
-        foreach ($data['targets'] as $target) {
-            if (!is_string($target)) {
-                throw new InvalidArgumentException(self::ERR_INVALID_TARGETS);
-            }
-        }
-		
-		return $this->manager->providerExtant($tenantId, $userId, $data['targets']);
+		return $this->mailManager->providerExtant($tenantId, $userId, $sources);
 
     }
 
@@ -240,17 +218,13 @@ class DefaultController extends ControllerAbstract {
 
     private function serviceList(string $tenantId, string $userId, array $data): mixed {
 
-        $targets = null;
-        if (isset($data['targets']) && is_array($data['targets'])) {
-            $targets = ResourceIdentifiers::fromArray($data['targets']);
-            foreach ($targets as $target) {
-                if (!$target instanceof CollectionIdentifier && !$target instanceof ServiceIdentifier) {
-                    throw new InvalidArgumentException('Invalid parameter: targets must contain provider:service, provider:service:collection, or provider:service:collection:entity identifiers');
-                }
-            }
+        $sources = null;
+        if (isset($data['sources']) && is_array($data['sources'])) {
+            $sources = new SourceSelector();
+            $sources->jsonDeserialize($data['sources']);
         }
 
-        return $this->manager->serviceList($tenantId, $userId, $targets);
+        return $this->mailManager->serviceList($tenantId, $userId, $sources);
 
     }
 
@@ -269,25 +243,21 @@ class DefaultController extends ControllerAbstract {
 			throw new InvalidArgumentException(self::ERR_INVALID_IDENTIFIER);
 		}
         
-        return $this->manager->serviceFetch($tenantId, $userId, $data['provider'], $data['identifier']);
+        return $this->mailManager->serviceFetch($tenantId, $userId, $data['provider'], $data['identifier']);
     }
 
     private function serviceExtant(string $tenantId, string $userId, array $data): mixed {
         
-        if (!isset($data['targets'])) {
-			throw new InvalidArgumentException(self::ERR_MISSING_TARGETS);
+        if (!isset($data['sources'])) {
+			throw new InvalidArgumentException(self::ERR_MISSING_SOURCES);
 		}
-		if (!is_array($data['targets'])) {
-			throw new InvalidArgumentException(self::ERR_INVALID_TARGETS);
-		}
-		$targets = ResourceIdentifiers::fromArray($data['targets']);
-		foreach ($targets as $target) {
-			if (!$target instanceof ServiceIdentifier) {
-				throw new InvalidArgumentException('Invalid parameter: targets must contain provider:service identifiers');
-			}
+		if (!is_array($data['sources'])) {
+			throw new InvalidArgumentException(self::ERR_INVALID_SOURCES);
 		}
+		$sources = new SourceSelector();
+		$sources->jsonDeserialize($data['sources']);
 		
-		return $this->manager->serviceExtant($tenantId, $userId, $targets);
+		return $this->mailManager->serviceExtant($tenantId, $userId, $sources);
     }
 
     private function serviceCreate(string $tenantId, string $userId, array $data): mixed {
@@ -304,7 +274,7 @@ class DefaultController extends ControllerAbstract {
             throw new InvalidArgumentException(self::ERR_INVALID_DATA);
         }
         
-        return $this->manager->serviceCreate(
+        return $this->mailManager->serviceCreate(
             $tenantId,
             $userId,
             $data['provider'],
@@ -335,7 +305,7 @@ class DefaultController extends ControllerAbstract {
             throw new InvalidArgumentException('Invalid parameter: delta must be a boolean');
         }
         
-        return $this->manager->serviceUpdate(
+        return $this->mailManager->serviceUpdate(
             $tenantId,
             $userId,
             $data['provider'],
@@ -359,7 +329,7 @@ class DefaultController extends ControllerAbstract {
             throw new InvalidArgumentException(self::ERR_INVALID_IDENTIFIER);
         }
         
-        return $this->manager->serviceDelete(
+        return $this->mailManager->serviceDelete(
             $tenantId,
             $userId,
             $data['provider'],
@@ -380,7 +350,7 @@ class DefaultController extends ControllerAbstract {
             throw new InvalidArgumentException('Either a service identifier or location and identity must be provided for service test');
         }
         
-        return $this->manager->serviceTest(
+        return $this->mailManager->serviceTest(
             $tenantId,
             $userId,
             $data['provider'],
@@ -401,7 +371,7 @@ class DefaultController extends ControllerAbstract {
         $location  = $data['location'] ?? null;
         $secret    = $data['secret'] ?? null;
 
-        $discoverGenerator = $this->manager->serviceDiscover($tenantId, $userId, $provider, $identity, $location, $secret);
+        $discoverGenerator = $this->mailManager->serviceDiscover($tenantId, $userId, $provider, $identity, $location, $secret);
         $logger            = $this->logger;
 
         $response = (function () use ($discoverGenerator, $version, $transaction, $logger): \Generator {
@@ -439,18 +409,20 @@ class DefaultController extends ControllerAbstract {
     private function collectionList(string $tenantId, string $userId, array $data): mixed {
         $sources = null;
         if (isset($data['sources']) && is_array($data['sources'])) {
+            // TODO: Refactor to use identifiers directly
             $sources = ResourceIdentifiers::fromArray($data['sources']);
             foreach ($sources as $source) {
                 if (!$source instanceof CollectionIdentifier && !$source instanceof ServiceIdentifier) {
                     throw new InvalidArgumentException('Invalid parameter: sources must contain provider:service, provider:service:collection, or provider:service:collection:entity identifiers');
                 }
             }
+            $sources = $this->createSourceSelectorFromIdentifiers($sources);
         }
         
         $filter = $data['filter'] ?? null;
         $sort = $data['sort'] ?? null;
         
-        return $this->manager->collectionList($tenantId, $userId, $sources, $filter, $sort);
+        return $this->mailManager->collectionList($tenantId, $userId, $sources, $filter, $sort);
     }
 
     private function collectionFetch(string $tenantId, string $userId, array $data): mixed {
@@ -461,6 +433,7 @@ class DefaultController extends ControllerAbstract {
             throw new InvalidArgumentException(self::ERR_INVALID_TARGETS);
         }
 
+        // TODO: Refactor to use identifiers directly
         $targetIdentifiers = ResourceIdentifiers::fromArray($data['targets']);
         foreach ($targetIdentifiers as $targetIdentifier) {
             if (!$targetIdentifier instanceof CollectionIdentifier) {
@@ -468,11 +441,16 @@ class DefaultController extends ControllerAbstract {
             }
         }
 
-        $list = $this->manager->collectionFetch(
-            $tenantId,
-            $userId,
-            $targetIdentifier
-        );
+        $list = [];
+        foreach ($targetIdentifiers as $targetIdentifier) {
+             $list[(string)$targetIdentifier] = $this->mailManager->collectionFetch(
+                $tenantId,
+                $userId,
+                $targetIdentifier->provider(),
+                $targetIdentifier->service(),
+                $targetIdentifier->collection()
+            );
+        }
         return $list;
     }
 
@@ -484,14 +462,16 @@ class DefaultController extends ControllerAbstract {
             throw new InvalidArgumentException(self::ERR_INVALID_TARGETS);
         }
         
+        // TODO: Refactor to use identifiers directly
         $sources = ResourceIdentifiers::fromArray($data['targets']);
         foreach ($sources as $source) {
             if (!$source instanceof CollectionIdentifier) {
                 throw new InvalidArgumentException('Invalid parameter: targets must contain provider:service, provider:service:collection, or provider:service:collection:entity identifiers');
             }
         }
+        $sources = $this->createSourceSelectorFromIdentifiers($sources);
         
-        return $this->manager->collectionExtant($tenantId, $userId, $sources);
+        return $this->mailManager->collectionExtant($tenantId, $userId, $sources);
     }
 
     private function collectionCreate(string $tenantId, string $userId, array $data): mixed {
@@ -524,7 +504,7 @@ class DefaultController extends ControllerAbstract {
             }
         }
         
-        return $this->manager->collectionCreate(
+        return $this->mailManager->collectionCreate(
             $tenantId,
             $userId,
             $data['provider'],
@@ -553,7 +533,7 @@ class DefaultController extends ControllerAbstract {
             throw new InvalidArgumentException('Invalid parameter: target must be provider:service:collection');
         }
         
-        return $this->manager->collectionUpdate(
+        return $this->mailManager->collectionUpdate(
             $tenantId,
             $userId,
             $targetIdentifier,
@@ -574,18 +554,18 @@ class DefaultController extends ControllerAbstract {
             throw new InvalidArgumentException('Invalid parameter: target must be provider:service:collection');
         }
         
-        $result = $this->manager->collectionDelete($tenantId, $userId, $targetIdentifier, $data['options'] ?? [] );
+        $result = $this->mailManager->collectionDelete($tenantId, $userId, $targetIdentifier, $data['options'] ?? [] );
         
         if (is_bool($result)) {
             return [
-                'disposition' => 'deleted'
+                'outcome' => 'deleted'
             ];
         }
 
         if ($result instanceof JsonSerializable) {
             return [
-                'disposition' => 'moved',
-                'mutation' => $result
+                'outcome' => 'moved',
+                'data' => $result
             ];
         }
 
@@ -617,7 +597,7 @@ class DefaultController extends ControllerAbstract {
 
         }
         
-        return $this->manager->collectionMove($tenantId, $userId, $target, $source);
+        return $this->mailManager->collectionMove($tenantId, $userId, $target, $source);
     }
 
     // ==================== Entity Operations ====================
@@ -637,11 +617,13 @@ class DefaultController extends ControllerAbstract {
             }
         }
 
+        $sources = $this->createSourceSelectorFromIdentifiers($sources);
+        
 		$filter = $data['filter'] ?? null;
 		$sort = $data['sort'] ?? null;
 		$range = $data['range'] ?? null;
 
-		return $this->manager->entityListBulk($tenantId, $userId, $sources, $filter, $sort, $range);
+		return $this->mailManager->entityListBulk($tenantId, $userId, $sources, $filter, $sort, $range);
 
     }
 
@@ -660,11 +642,13 @@ class DefaultController extends ControllerAbstract {
             }
         }
 
+        $sources = $this->createSourceSelectorFromIdentifiers($sources);
+
         $filter = $data['filter'] ?? null;
         $sort   = $data['sort'] ?? null;
         $range  = $data['range'] ?? null;
 
-        $entityGenerator = $this->manager->entityListStream($tenantId, $userId, $sources, $filter, $sort, $range);
+        $entityGenerator = $this->mailManager->entityListStream($tenantId, $userId, $sources, $filter, $sort, $range);
         $logger          = $this->logger;
 
         $responseGenerator = (function () use ($entityGenerator, $version, $transaction, $logger): \Generator {
@@ -694,6 +678,50 @@ class DefaultController extends ControllerAbstract {
         return new StreamedNdJsonResponse($responseGenerator, 1, 200, ['Content-Type' => 'application/json']);
     }
 
+    private function createSourceSelectorFromIdentifiers(ResourceIdentifiers $identifiers): SourceSelector {
+        $sources = new SourceSelector();
+
+        foreach ($identifiers as $identifier) {
+            if (!$identifier instanceof ServiceIdentifier) {
+                throw new InvalidArgumentException('Invalid parameter: sources must contain provider:service, provider:service:collection, or provider:service:collection:entity identifiers');
+            }
+
+            $provider = $identifier->provider();
+            $service = $identifier->service();
+
+            if (!isset($sources[$provider])) {
+                $sources[$provider] = new ServiceSelector();
+            }
+
+            $serviceSelector = $sources[$provider];
+            if (!$serviceSelector instanceof ServiceSelector) {
+                throw new InvalidArgumentException('Invalid parameter: sources must contain provider:service:collection selectors');
+            }
+
+            if ($identifier instanceof ServiceIdentifier && !$identifier instanceof CollectionIdentifier) {
+                $serviceSelector[$service] = true;
+                continue;
+            }
+
+            if (isset($serviceSelector[$service]) && $serviceSelector[$service] === true) {
+                continue;
+            }
+
+            if (!isset($serviceSelector[$service])) {
+                $serviceSelector[$service] = new CollectionSelector();
+            }
+
+            $collectionSelector = $serviceSelector[$service];
+            if (!$collectionSelector instanceof CollectionSelector) {
+                throw new InvalidArgumentException('Invalid parameter: sources must contain provider:service:collection selectors');
+            }
+
+            $collectionSelector[$identifier->collection()] = true;
+        }
+
+        return $sources;
+    }
+
     private function entityFetch(string $tenantId, string $userId, array $data): mixed {
         if (!isset($data['targets'])) {
             throw new InvalidArgumentException(self::ERR_MISSING_TARGETS);
@@ -709,7 +737,7 @@ class DefaultController extends ControllerAbstract {
             }
         }
         
-        return $this->manager->entityFetchBulk(
+        return $this->mailManager->entityFetchBulk(
             $tenantId,
             $userId,
             ...$targets->all()
@@ -717,88 +745,49 @@ class DefaultController extends ControllerAbstract {
     }
 
     private function entityExtant(string $tenantId, string $userId, array $data): mixed {
-        if (!isset($data['targets'])) {
-            throw new InvalidArgumentException(self::ERR_MISSING_TARGETS);
+        if (!isset($data['sources'])) {
+            throw new InvalidArgumentException(self::ERR_MISSING_SOURCES);
         }
-        if (!is_array($data['targets'])) {
-            throw new InvalidArgumentException(self::ERR_INVALID_TARGETS);
+        if (!is_array($data['sources'])) {
+            throw new InvalidArgumentException(self::ERR_INVALID_SOURCES);
         }
         
-        $targets = ResourceIdentifiers::fromArray($data['targets']);
-        foreach ($targets as $target) {
-            if (!$target instanceof CollectionIdentifier && !$target instanceof EntityIdentifier) {
-                throw new InvalidArgumentException('Invalid parameter: targets must contain provider:service:collection or provider:service:collection:entity identifiers');
-            }
-        }
+        $sources = new SourceSelector();
+        $sources->jsonDeserialize($data['sources']);
         
-        return $this->manager->entityExtant($tenantId, $userId, $targets);
+        return $this->mailManager->entityExtant($tenantId, $userId, $sources);
     }
 
     private function entityDelta(string $tenantId, string $userId, array $data): mixed {
-        if (!isset($data['targets'])) {
-            throw new InvalidArgumentException(self::ERR_MISSING_TARGETS);
+        if (!isset($data['sources'])) {
+            throw new InvalidArgumentException(self::ERR_MISSING_SOURCES);
         }
-        if (!is_array($data['targets'])) {
-            throw new InvalidArgumentException(self::ERR_INVALID_TARGETS);
+        if (!is_array($data['sources'])) {
+            throw new InvalidArgumentException(self::ERR_INVALID_SOURCES);
         }
         
-        $targets = ResourceIdentifiers::fromArray($data['targets']);
-        foreach ($targets as $target) {
-            if (!$target instanceof CollectionIdentifier && !$target instanceof EntityIdentifier) {
-                throw new InvalidArgumentException('Invalid parameter: targets must contain provider:service:collection or provider:service:collection:signature identifiers');
+        $sources = new SourceSelector();
+        $sources->jsonDeserialize($data['sources']);
+        
+        return $this->mailManager->entityDelta($tenantId, $userId, $sources);
+    }
+
+    private function entityDelete(string $tenantId, string $userId, array $data): mixed {
+        if (!isset($data['sources'])) {
+            throw new InvalidArgumentException(self::ERR_MISSING_SOURCES);
+        }
+        if (!is_array($data['sources'])) {
+            throw new InvalidArgumentException(self::ERR_INVALID_SOURCES);
+        }
+
+        $sources = ResourceIdentifiers::fromArray($data['sources']);
+        foreach ($sources as $source) {
+            if (!$source instanceof EntityIdentifier) {
+                throw new InvalidArgumentException('Invalid parameter: sources must contain provider:service:collection:entity identifiers');
             }
         }
         
-        return $this->manager->entityDelta($tenantId, $userId, $targets);
-    }
-
-    private function entityCreate(string $tenantId, string $userId, array $data = []): mixed {
-        if (!isset($data['target'])) {
-            throw new InvalidArgumentException(self::ERR_MISSING_TARGET);
-        }
-        if (!is_string($data['target'])) {
-            throw new InvalidArgumentException(self::ERR_INVALID_TARGET);
-        }
-        if (!isset($data['properties'])) {
-            throw new InvalidArgumentException(self::ERR_MISSING_DATA);
-        }
-        if (!is_array($data['properties'])) {
-            throw new InvalidArgumentException(self::ERR_INVALID_DATA);
-        }
-
-        $target = ResourceIdentifier::fromString($data['target']);
-        if (!$target instanceof CollectionIdentifier) {
-            throw new InvalidArgumentException('Invalid parameter: target must be provider:service:collection');
-        }
-
-        $options = $data['options'] ?? [];
-        if (!is_array($options)) {
-            throw new InvalidArgumentException(self::ERR_INVALID_DATA);
-        }
-
-        return $this->manager->entityCreate($tenantId, $userId, $target, $data['properties'], $options);
-    }
-
-    private function entityUpdate(string $tenantId, string $userId, array $data = []): mixed {
-        if (!isset($data['target'])) {
-            throw new InvalidArgumentException(self::ERR_MISSING_TARGET);
-        }
-        if (!is_string($data['target'])) {
-            throw new InvalidArgumentException(self::ERR_INVALID_TARGET);
-        }
-        if (!isset($data['properties'])) {
-            throw new InvalidArgumentException(self::ERR_MISSING_DATA);
-        }
-        if (!is_array($data['properties'])) {
-            throw new InvalidArgumentException(self::ERR_INVALID_DATA);
-        }
-
-        $target = ResourceIdentifier::fromString($data['target']);
-        if (!$target instanceof EntityIdentifier) {
-            throw new InvalidArgumentException('Invalid parameter: target must be provider:service:collection:entity');
-        }
-
-        return $this->manager->entityModify($tenantId, $userId, $target, $data['properties']);
+        return $this->mailManager->entityDelete($tenantId, $userId, ...$sources->all());
     }
 
     private function entityPatch(string $tenantId, string $userId, array $data): mixed {
@@ -822,25 +811,7 @@ class DefaultController extends ControllerAbstract {
             }
         }
         
-        return $this->manager->entityPatch($tenantId, $userId, $data['properties'], ...$targets->all());
-    }
-
-    private function entityDelete(string $tenantId, string $userId, array $data): mixed {
-        if (!isset($data['targets'])) {
-            throw new InvalidArgumentException(self::ERR_MISSING_TARGETS);
-        }
-        if (!is_array($data['targets'])) {
-            throw new InvalidArgumentException(self::ERR_INVALID_TARGETS);
-        }
-
-        $targets = ResourceIdentifiers::fromArray($data['targets']);
-        foreach ($targets as $target) {
-            if (!$target instanceof EntityIdentifier) {
-                throw new InvalidArgumentException('Invalid parameter: targets must contain provider:service:collection:entity identifiers');
-            }
-        }
-        
-        return $this->manager->entityDelete($tenantId, $userId, ...$targets->all());
+        return $this->mailManager->entityPatch($tenantId, $userId, $data['properties'], ...$targets->all());
     }
 
     private function entityMove(string $tenantId, string $userId, array $data): mixed {
@@ -869,136 +840,32 @@ class DefaultController extends ControllerAbstract {
             }
         }
         
-        return $this->manager->entityMove($tenantId, $userId, $target, ...$sources->all());
+        return $this->mailManager->entityMove($tenantId, $userId, $target, ...$sources->all());
     }
 
-    private function entitySubmit(string $tenantId, string $userId, array $data): mixed {
-        if (!isset($data['sender'])) {
-            throw new InvalidArgumentException(self::ERR_MISSING_SENDER);
+    private function entityTransmit(string $tenantId, string $userId, array $data): mixed {
+        if (!isset($data['provider'])) {
+            throw new InvalidArgumentException(self::ERR_MISSING_PROVIDER);
         }
-        if (!is_string($data['sender'])) {
-            throw new InvalidArgumentException(self::ERR_INVALID_SENDER);
+        if (!is_string($data['provider'])) {
+            throw new InvalidArgumentException(self::ERR_INVALID_PROVIDER);
+        }
+        if (!isset($data['service'])) {
+            throw new InvalidArgumentException(self::ERR_MISSING_SERVICE);
+        }
+        if (!is_string($data['service'])) {
+            throw new InvalidArgumentException(self::ERR_INVALID_SERVICE);
         }
         
-        return $this->manager->entitySubmit(
+        $jobId = $this->mailManager->entityTransmit(
             $tenantId,
             $userId,
-            $data['sender'],
-            $data['source'] ?? null,
-            $data['message'] ?? null,
-        );
-    }
-
-    private function entityDownload(string $tenantId, string $userId, array $data): mixed {
-        if (!isset($data['target'])) {
-            throw new InvalidArgumentException(self::ERR_MISSING_TARGET);
-        }
-        if (!is_string($data['target'])) {
-            throw new InvalidArgumentException(self::ERR_INVALID_IDENTIFIER);
-        }
-
-        // 'part' is optional — null means full RFC 822 message download
-        $part = isset($data['part']) && is_array($data['part']) ? $data['part'] : null;
-
-        $target = ResourceIdentifier::fromString($data['target']);
-        $logger = $this->logger;
-
-        $result = $this->manager->entityDownload($tenantId, $userId, $target, $part);
-
-        $filename       = $result->filename();
-        $asciiFilename  = preg_replace('/[^\x20-\x7E]|[\\\\"]/', '_', $filename);
-        $encodedFilename = rawurlencode($filename);
-        $disposition    = sprintf(
-            'attachment; filename="%s"; filename*=UTF-8\'\'%s',
-            $asciiFilename,
-            $encodedFilename,
+            $data['provider'],
+            $data['service'],
+            $data['data']
         );
         
-        $responseGenerator = (static function () use ($result, $logger): \Generator {
-            try {
-                yield from $result->stream();
-            } catch (\Throwable $t) {
-                $logger->error('Error streaming entity download', ['exception' => $t]);
-                // Headers already sent — cannot change status code; stop output cleanly
-            }
-        })();
-
-        return new StreamedResponse($responseGenerator, 200, [
-            'Content-Disposition'       => $disposition,
-            'Content-Type'              => $result->mimeType(),
-            'Content-Transfer-Encoding' => 'binary',
-            'Cache-Control'             => 'no-store',
-        ]);
-    }
-    
-    private function entityBlobs(string $tenantId, string $userId, array $data): mixed {
-        if (!isset($data['target'])) {
-            throw new InvalidArgumentException(self::ERR_MISSING_TARGET);
-        }
-        if (!is_string($data['target'])) {
-            throw new InvalidArgumentException(self::ERR_INVALID_IDENTIFIER);
-        }
-        if (!isset($data['parts']) || !is_array($data['parts']) || $data['parts'] === []) {
-            throw new InvalidArgumentException('At least one part selector is required');
-        }
-
-        $target = ResourceIdentifier::fromString($data['target']);
-
-        $results = [];
-        foreach ($data['parts'] as $part) {
-            if (!is_array($part)) {
-                throw new InvalidArgumentException('Invalid part selector');
-            }
-
-            $resource = $this->manager->entityDownload($tenantId, $userId, $target, $part);
-
-            $bytes = '';
-            foreach ($resource->stream() as $chunk) {
-                $bytes .= $chunk;
-            }
-
-            $results[] = [
-                'source'   => $data['target'],
-                'part'     => $part,
-                'mime'     => $resource->mimeType(),
-                'filename' => $resource->filename(),
-                'bytes'    => base64_encode($bytes),
-            ];
-        }
-
-        return $results;
-    }
-
-    private function entityPreview(string $tenantId, string $userId, array $data): Response {
-        if (!isset($data['target']) || !is_string($data['target'])) {
-            throw new InvalidArgumentException(self::ERR_MISSING_TARGET);
-        }
-        if (!isset($data['part']) || !is_array($data['part'])) {
-            throw new InvalidArgumentException('Attachment preview requires a part');
-        }
-
-        $target = ResourceIdentifier::fromString($data['target']);
-        if (!$target instanceof EntityIdentifier) {
-            throw new InvalidArgumentException(self::ERR_INVALID_IDENTIFIER);
-        }
-        $preview = $this->manager->entityPreview(
-            $tenantId,
-            $userId,
-            $target,
-            $data['part'],
-            isset($data['variant']) && is_string($data['variant']) ? $data['variant'] : 'inline',
-        );
-        if ($preview === null) {
-            return new Response('', Response::HTTP_NO_CONTENT);
-        }
-
-        return new StreamedResponse($preview->resource->stream(), Response::HTTP_OK, [
-            'Content-Type' => $preview->resource->mimeType(),
-            'Content-Length' => (string) $preview->size,
-            'ETag' => '"' . trim($preview->etag, '"') . '"',
-            'Cache-Control' => 'private, max-age=3600',
-            'X-Content-Type-Options' => 'nosniff',
-        ]);
+        return ['jobId' => $jobId];
     }
 
 }

lib/Daemon/MailDaemon.php

@@ -0,0 +1,237 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXM\MailManager\Daemon;
+
+use KTXM\MailManager\Manager;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Mail Queue Daemon
+ * 
+ * Long-running worker process for processing queued mail messages.
+ * Supports graceful shutdown via signals and configurable batch processing.
+ * 
+ * @since 2025.05.01
+ */
+class MailDaemon {
+
+    private bool $running = false;
+    private bool $shutdown = false;
+    private bool $reload = false;
+
+    /**
+     * @param Manager $manager Mail manager
+     * @param LoggerInterface $logger Logger
+     * @param int $pollInterval Seconds between queue polls when idle
+     * @param int $batchSize Messages to process per batch
+     * @param int|null $maxMemory Maximum memory usage in bytes before restart
+     * @param array<string>|null $tenants Specific tenants to process (null = all)
+     */
+    public function __construct(
+        private Manager $manager,
+        private LoggerInterface $logger,
+        private int $pollInterval = 5,
+        private int $batchSize = 50,
+        private ?int $maxMemory = null,
+        private ?array $tenants = null,
+    ) {
+        // Set default max memory to 128MB
+        $this->maxMemory = $this->maxMemory ?? (128 * 1024 * 1024);
+    }
+
+    /**
+     * Run the daemon main loop
+     * 
+     * @since 2025.05.01
+     */
+    public function run(): void {
+        $this->running = true;
+        $this->shutdown = false;
+        
+        $this->setupSignalHandlers();
+        
+        $this->logger->info('Mail daemon starting', [
+            'pollInterval' => $this->pollInterval,
+            'batchSize' => $this->batchSize,
+            'maxMemory' => $this->formatBytes($this->maxMemory),
+            'tenants' => $this->tenants ?? 'all',
+        ]);
+        
+        $consecutiveEmpty = 0;
+        
+        while (!$this->shutdown) {
+            // Handle reload signal
+            if ($this->reload) {
+                $this->handleReload();
+                $this->reload = false;
+            }
+            
+            // Check memory usage
+            if ($this->isMemoryExceeded()) {
+                $this->logger->warning('Memory limit exceeded, shutting down for restart', [
+                    'current' => $this->formatBytes(memory_get_usage(true)),
+                    'limit' => $this->formatBytes($this->maxMemory),
+                ]);
+                break;
+            }
+            
+            // Process queues
+            $processed = $this->processTenants();
+            
+            if ($processed === 0) {
+                $consecutiveEmpty++;
+                // Exponential backoff up to poll interval
+                $sleepTime = min($consecutiveEmpty, $this->pollInterval);
+                $this->sleep($sleepTime);
+            } else {
+                $consecutiveEmpty = 0;
+            }
+            
+            // Dispatch pending signals
+            pcntl_signal_dispatch();
+        }
+        
+        $this->logger->info('Mail daemon stopped');
+        $this->running = false;
+    }
+
+    /**
+     * Request graceful shutdown
+     * 
+     * @since 2025.05.01
+     */
+    public function stop(): void {
+        $this->shutdown = true;
+    }
+
+    /**
+     * Check if daemon is running
+     * 
+     * @since 2025.05.01
+     * 
+     * @return bool
+     */
+    public function isRunning(): bool {
+        return $this->running;
+    }
+
+    /**
+     * Process all tenants and return total messages processed
+     */
+    private function processTenants(): int {
+        $totalProcessed = 0;
+        $tenants = $this->tenants ?? $this->discoverTenants();
+        
+        foreach ($tenants as $tenantId) {
+            if ($this->shutdown) {
+                break;
+            }
+            
+            $result = $this->manager->queueProcess($tenantId, $this->batchSize);
+            $totalProcessed += $result['processed'] + $result['failed'];
+            
+            if ($result['processed'] > 0 || $result['failed'] > 0) {
+                $this->logger->debug('Processed tenant queue', [
+                    'tenant' => $tenantId,
+                    'processed' => $result['processed'],
+                    'failed' => $result['failed'],
+                ]);
+            }
+        }
+        
+        return $totalProcessed;
+    }
+
+    /**
+     * Discover all tenants with mail queues
+     * 
+     * @return array<string>
+     */
+    private function discoverTenants(): array {
+        // This would need to be implemented based on your tenant discovery mechanism
+        // For now, return empty array - specific tenants should be configured
+        return [];
+    }
+
+    /**
+     * Setup signal handlers for graceful shutdown
+     */
+    private function setupSignalHandlers(): void {
+        if (!function_exists('pcntl_signal')) {
+            $this->logger->warning('PCNTL extension not available, signal handling disabled');
+            return;
+        }
+        
+        pcntl_signal(SIGTERM, function() {
+            $this->logger->info('Received SIGTERM, initiating graceful shutdown');
+            $this->shutdown = true;
+        });
+        
+        pcntl_signal(SIGINT, function() {
+            $this->logger->info('Received SIGINT, initiating graceful shutdown');
+            $this->shutdown = true;
+        });
+        
+        pcntl_signal(SIGHUP, function() {
+            $this->logger->info('Received SIGHUP, will reload configuration');
+            $this->reload = true;
+        });
+    }
+
+    /**
+     * Handle configuration reload
+     */
+    private function handleReload(): void {
+        $this->logger->info('Reloading configuration');
+        // Configuration reload logic would go here
+    }
+
+    /**
+     * Check if memory limit has been exceeded
+     */
+    private function isMemoryExceeded(): bool {
+        if ($this->maxMemory === null) {
+            return false;
+        }
+        
+        return memory_get_usage(true) > $this->maxMemory;
+    }
+
+    /**
+     * Sleep with signal dispatch
+     */
+    private function sleep(int $seconds): void {
+        for ($i = 0; $i < $seconds; $i++) {
+            if ($this->shutdown) {
+                return;
+            }
+            sleep(1);
+            pcntl_signal_dispatch();
+        }
+    }
+
+    /**
+     * Format bytes to human readable string
+     */
+    private function formatBytes(?int $bytes): string {
+        if ($bytes === null) {
+            return 'unlimited';
+        }
+        
+        $units = ['B', 'KB', 'MB', 'GB'];
+        $i = 0;
+        while ($bytes >= 1024 && $i < count($units) - 1) {
+            $bytes /= 1024;
+            $i++;
+        }
+        return round($bytes, 2) . ' ' . $units[$i];
+    }
+
+}

lib/Daemon/MailQueueCli.php

@@ -0,0 +1,246 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXM\MailManager\Daemon;
+
+use KTXM\MailManager\Queue\JobStatus;
+use KTXM\MailManager\Queue\MailQueue;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Mail Queue CLI
+ * 
+ * Command-line interface for mail queue management operations.
+ * 
+ * Usage:
+ *   php mail-queue.php list <tenant> [--status=pending]
+ *   php mail-queue.php retry <jobId>
+ *   php mail-queue.php retry-all <tenant> --status=failed
+ *   php mail-queue.php purge <tenant> --status=complete --older-than=7d
+ *   php mail-queue.php stats <tenant>
+ * 
+ * @since 2025.05.01
+ */
+class MailQueueCli {
+
+    public function __construct(
+        private MailQueue $queue,
+        private LoggerInterface $logger,
+    ) {}
+
+    /**
+     * Run CLI command
+     * 
+     * @param array<string> $args Command line arguments
+     * 
+     * @return int Exit code
+     */
+    public function run(array $args): int {
+        $command = $args[1] ?? 'help';
+        
+        return match($command) {
+            'list' => $this->commandList($args),
+            'retry' => $this->commandRetry($args),
+            'retry-all' => $this->commandRetryAll($args),
+            'purge' => $this->commandPurge($args),
+            'stats' => $this->commandStats($args),
+            'help', '--help', '-h' => $this->commandHelp(),
+            default => $this->commandHelp(),
+        };
+    }
+
+    /**
+     * List jobs in queue
+     */
+    private function commandList(array $args): int {
+        $tenantId = $args[2] ?? null;
+        if ($tenantId === null) {
+            echo "Error: tenant ID required\n";
+            return 1;
+        }
+        
+        $status = $this->parseOption($args, 'status');
+        $statusEnum = $status !== null ? JobStatus::tryFrom($status) : null;
+        $limit = (int)($this->parseOption($args, 'limit') ?? 100);
+        
+        $jobs = $this->queue->listJobs($tenantId, $statusEnum, $limit);
+        
+        if (empty($jobs)) {
+            echo "No jobs found\n";
+            return 0;
+        }
+        
+        echo sprintf("%-36s %-12s %-8s %-20s %s\n", 
+            'JOB ID', 'STATUS', 'ATTEMPTS', 'CREATED', 'SUBJECT');
+        echo str_repeat('-', 100) . "\n";
+        
+        foreach ($jobs as $job) {
+            $subject = substr($job->message->getSubject(), 0, 30);
+            echo sprintf("%-36s %-12s %-8d %-20s %s\n",
+                $job->id,
+                $job->status->value,
+                $job->attempts,
+                $job->created?->format('Y-m-d H:i:s') ?? '-',
+                $subject
+            );
+        }
+        
+        return 0;
+    }
+
+    /**
+     * Retry a specific job
+     */
+    private function commandRetry(array $args): int {
+        $jobId = $args[2] ?? null;
+        if ($jobId === null) {
+            echo "Error: job ID required\n";
+            return 1;
+        }
+        
+        if ($this->queue->retry($jobId)) {
+            echo "Job $jobId queued for retry\n";
+            return 0;
+        }
+        
+        echo "Failed to retry job $jobId (not found or not failed)\n";
+        return 1;
+    }
+
+    /**
+     * Retry all failed jobs for a tenant
+     */
+    private function commandRetryAll(array $args): int {
+        $tenantId = $args[2] ?? null;
+        if ($tenantId === null) {
+            echo "Error: tenant ID required\n";
+            return 1;
+        }
+        
+        $jobs = $this->queue->listJobs($tenantId, JobStatus::Failed);
+        $retried = 0;
+        
+        foreach ($jobs as $job) {
+            if ($this->queue->retry($job->id)) {
+                $retried++;
+            }
+        }
+        
+        echo "Retried $retried jobs\n";
+        return 0;
+    }
+
+    /**
+     * Purge old jobs
+     */
+    private function commandPurge(array $args): int {
+        $tenantId = $args[2] ?? null;
+        if ($tenantId === null) {
+            echo "Error: tenant ID required\n";
+            return 1;
+        }
+        
+        $status = $this->parseOption($args, 'status') ?? 'complete';
+        $statusEnum = JobStatus::tryFrom($status);
+        if ($statusEnum === null) {
+            echo "Error: invalid status '$status'\n";
+            return 1;
+        }
+        
+        $olderThan = $this->parseOption($args, 'older-than') ?? '7d';
+        $seconds = $this->parseDuration($olderThan);
+        
+        $purged = $this->queue->purge($tenantId, $statusEnum, $seconds);
+        echo "Purged $purged jobs\n";
+        
+        return 0;
+    }
+
+    /**
+     * Show queue statistics
+     */
+    private function commandStats(array $args): int {
+        $tenantId = $args[2] ?? null;
+        if ($tenantId === null) {
+            echo "Error: tenant ID required\n";
+            return 1;
+        }
+        
+        $stats = $this->queue->stats($tenantId);
+        
+        echo "Queue Statistics for $tenantId:\n";
+        echo "  Pending:    {$stats['pending']}\n";
+        echo "  Processing: {$stats['processing']}\n";
+        echo "  Complete:   {$stats['complete']}\n";
+        echo "  Failed:     {$stats['failed']}\n";
+        
+        return 0;
+    }
+
+    /**
+     * Show help message
+     */
+    private function commandHelp(): int {
+        echo <<<HELP
+Mail Queue CLI
+
+Usage:
+  mail-queue <command> [options]
+
+Commands:
+  list <tenant>              List jobs in queue
+    --status=<status>        Filter by status (pending, processing, complete, failed)
+    --limit=<n>              Maximum jobs to show (default: 100)
+
+  retry <jobId>              Retry a specific failed job
+
+  retry-all <tenant>         Retry all failed jobs for a tenant
+
+  purge <tenant>             Purge old jobs
+    --status=<status>        Status to purge (default: complete)
+    --older-than=<duration>  Age threshold (default: 7d, e.g., 1h, 30d)
+
+  stats <tenant>             Show queue statistics
+
+  help                       Show this help message
+
+HELP;
+        return 0;
+    }
+
+    /**
+     * Parse a command line option
+     */
+    private function parseOption(array $args, string $name): ?string {
+        foreach ($args as $arg) {
+            if (str_starts_with($arg, "--$name=")) {
+                return substr($arg, strlen("--$name="));
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Parse a duration string to seconds
+     */
+    private function parseDuration(string $duration): int {
+        preg_match('/^(\d+)([smhd])?$/', $duration, $matches);
+        $value = (int)($matches[1] ?? 0);
+        $unit = $matches[2] ?? 's';
+        
+        return match($unit) {
+            's' => $value,
+            'm' => $value * 60,
+            'h' => $value * 3600,
+            'd' => $value * 86400,
+            default => $value,
+        };
+    }
+
+}

lib/Manager.php

@@ -5,17 +5,11 @@ declare(strict_types=1);
 namespace KTXM\MailManager;
 
 use InvalidArgumentException;
-use KTXC\Preview\Preview;
-use KTXC\Preview\PreviewManager;
 use KTXC\Resource\ProviderManager;
-use KTXF\Preview\PreviewSource;
 use KTXF\Mail\Collection\CollectionBaseInterface;
 use KTXF\Mail\Collection\CollectionPropertiesMutableInterface;
 use KTXF\Mail\Collection\ICollectionBase;
-use KTXF\Mail\Entity\EntityBaseInterface;
 use KTXF\Mail\Entity\IMessageBase;
-use KTXF\Mail\Object\Address;
-use KTXF\Mail\Object\AddressInterface;
 use KTXF\Mail\Object\MessagePropertiesMutableInterface;
 use KTXF\Mail\Provider\ProviderBaseInterface;
 use KTXF\Mail\Provider\ProviderServiceDiscoverInterface;
@@ -25,18 +19,19 @@ use KTXF\Mail\Service\ServiceBaseInterface;
 use KTXF\Mail\Service\ServiceCollectionMutableInterface;
 use KTXF\Mail\Service\ServiceConfigurableInterface;
 use KTXF\Mail\Service\ServiceEntityMutableInterface;
-use KTXF\Mail\Service\ServiceEntitySubmitInterface;
 use KTXF\Mail\Service\ServiceMutableInterface;
-use KTXF\Mail\Submission\EntitySubmitResult;
-use KTXF\Resource\BinaryResource;
 use KTXF\Resource\Filter\IFilter;
 use KTXF\Resource\Identifier\CollectionIdentifier;
 use KTXF\Resource\Identifier\EntityIdentifier;
-use KTXF\Resource\Identifier\EntityIdentifierInterface;
 use KTXF\Resource\Identifier\ResourceIdentifiers;
 use KTXF\Resource\Provider\ResourceServiceIdentityInterface;
 use KTXF\Resource\Provider\ResourceServiceLocationInterface;
+use KTXF\Resource\Range\RangeAnchorType;
 use KTXF\Resource\Range\RangeType;
+use KTXF\Resource\Selector\CollectionSelector;
+use KTXF\Resource\Selector\EntitySelector;
+use KTXF\Resource\Selector\ServiceSelector;
+use KTXF\Resource\Selector\SourceSelector;
 use KTXF\Resource\Sort\ISort;
 use Psr\Log\LoggerInterface;
 
@@ -50,19 +45,20 @@ class Manager {
     public function __construct(
         private LoggerInterface $logger,
         private ProviderManager $providerManager,
-        private PreviewManager $previewManager,
     ) { }
 
     /**
      * Retrieve available providers
      *
-     * @param ResourceIdentifiers|null $sources collection of provider identifiers
+     * @param SourceSelector|null $sources collection of provider identifiers
      * 
      * @return array<string,ProviderBaseInterface> collection of available providers e.g. ['provider1' => IProvider, 'provider2' => IProvider]
      */
-    public function providerList(string $tenantId, string $userId, array|null $targets = []): array {
+    public function providerList(string $tenantId, string $userId, ?SourceSelector $sources = null): array {
+        // determine filter from sources
+        $filter = ($sources !== null && $sources->identifiers() !== []) ? $sources->identifiers() : null;
         // retrieve providers from provider manager
-        return $this->providerManager->providers(ProviderBaseInterface::TYPE_MAIL, $targets ?: null);
+        return $this->providerManager->providers(ProviderBaseInterface::TYPE_MAIL, $filter);
     }
 
     /**
@@ -75,27 +71,27 @@ class Manager {
      * @return ProviderBaseInterface
      * @throws InvalidArgumentException
      */
-    public function providerFetch(string $tenantId, string $userId, string $target): ProviderBaseInterface {
+    public function providerFetch(string $tenantId, string $userId, string $provider): ProviderBaseInterface {
         // retrieve provider
-        $providers = $this->providerList($tenantId, $userId, [$target]);
-        if (!isset($providers[$target])) {
-            throw new InvalidArgumentException("Provider '$target' not found");
+        $providers = $this->providerList($tenantId, $userId, new SourceSelector([$provider => true]));
+        if (!isset($providers[$provider])) {
+            throw new InvalidArgumentException("Provider '$provider' not found");
         }
-        return $providers[$target];
+        return $providers[$provider];
     }
 
     /**
      * Confirm which providers are available
      *
-     * @param array<string> $targets collection of provider identifiers to confirm
+     * @param SourceSelector|null $sources collection of provider identifiers to confirm
      * 
      * @return array<string,bool> collection of providers and their availability status e.g. ['provider1' => true, 'provider2' => false]
      */
-    public function providerExtant(string $tenantId, string $userId, array $targets): array {
+    public function providerExtant(string $tenantId, string $userId, SourceSelector $sources): array {
         // determine which providers are available
-        $providersResolved = $this->providerList($tenantId, $userId, $targets);
+        $providersResolved = $this->providerList($tenantId, $userId, $sources);
         $providersAvailable = array_keys($providersResolved);
-        $providersUnavailable = array_diff($targets, $providersAvailable);
+        $providersUnavailable = array_diff($sources->identifiers(), $providersAvailable);
         // construct response data
         $responseData = array_merge(
             array_fill_keys($providersAvailable, true),
@@ -109,24 +105,18 @@ class Manager {
      *
      * @param string $tenantId tenant identifier
      * @param string $userId user identifier
-     * @param ResourceIdentifiers|null $targets list of provider and service identifiers
+     * @param SourceSelector|null $sources list of provider and service identifiers
      * 
      * @return array<string,<string,ServiceBaseInterface>> collections of available services e.g. ['provider1' => ['service1' => IServiceBase], 'provider2' => ['service2' => IServiceBase]]
      */
-    public function serviceList(string $tenantId, string $userId, ?ResourceIdentifiers $targets = null): array {
+    public function serviceList(string $tenantId, string $userId, ?SourceSelector $sources = null): array {
         // retrieve providers
-        $providerFilter = $targets !== null ? $targets->providers() : null;
-        $providers = $this->providerList($tenantId, $userId, $providerFilter);
+        $providers = $this->providerList($tenantId, $userId, $sources);
         // retrieve services for each provider
         $responseData = [];
         foreach ($providers as $provider) {
-            if ($targets !== null) {
-                $servicesSelected = $targets?->byProvider($provider->identifier()) ?: [];
-                $servicesFilter = $servicesSelected->services();
-            } else {
-                $servicesFilter = [];
-            }
-            $services = $provider->serviceList($tenantId, $userId, $servicesFilter);
+            $serviceFilter = $sources[$provider->identifier()] instanceof ServiceSelector ? $sources[$provider->identifier()]->identifiers() : [];
+            $services = $provider->serviceList($tenantId, $userId, $serviceFilter);
             $responseData[$provider->identifier()] = $services;
         }
         return $responseData;
@@ -158,23 +148,24 @@ class Manager {
      *
      * @param string $tenantId tenant identifier
      * @param string $userId user identifier
-     * @param ResourceIdentifiers $targets collection of provider and service identifiers to confirm
+     * @param SourceSelector|null $sources collection of provider and service identifiers to confirm
      * 
      * @return array<string,bool> collection of providers and their availability status e.g. ['provider1' => ['service1' => false], 'provider2' => ['service2' => true, 'service3' => true]]
      */
-    public function serviceExtant(string $tenantId, string $userId, ResourceIdentifiers $targets): array {
-        // retrieve available providers
-        $providersRequested = $targets->providers();
-        $providers = $this->providerList($tenantId, $userId, $providersRequested);
+    public function serviceExtant(string $tenantId, string $userId, SourceSelector $sources): array {
+        // retrieve providers
+        $providers = $this->providerList($tenantId, $userId, $sources);
+        $providersRequested = $sources->identifiers();
         $providersUnavailable = array_diff($providersRequested, array_keys($providers));
         
         // initialize response with unavailable providers
         $responseData = array_fill_keys($providersUnavailable, false);
         
         // retrieve services for each available provider
-        foreach ($providers as $providerId => $provider) {
-            $servicesRequested = $targets->byProvider($providerId)->services();
-            $responseData[$providerId] = $provider->serviceExtant($tenantId, $userId, ...$servicesRequested);
+        foreach ($providers as $provider) {
+            $serviceSelector = $sources[$provider->identifier()];
+            $serviceAvailability = $provider->serviceExtant($tenantId, $userId, ...$serviceSelector->identifiers());
+            $responseData[$provider->identifier()] = $serviceAvailability;
         }
         return $responseData;
     }
@@ -241,14 +232,7 @@ class Manager {
         $serviceId = $provider->serviceCreate($tenantId, $userId, $service);
         
         // Fetch and return the created service
-        $createdService = $provider->serviceFetch($tenantId, $userId, $serviceId);
-        if ($createdService === null) {
-            throw new \RuntimeException(
-                "Provider '$providerId' created service '$serviceId', but it could not be fetched"
-            );
-        }
-
-        return $createdService;
+        return $provider->serviceFetch($tenantId, $userId, $serviceId);
     }
 
     /**
@@ -352,7 +336,7 @@ class Manager {
         string|null $location = null,
         string|null $secret = null
     ): \Generator {
-        $providers = $this->providerList($tenantId, $userId, $providerId !== null ? [$providerId] : null);
+        $providers = $this->providerList($tenantId, $userId, $providerId !== null ? new SourceSelector([$providerId => true]) : null);
 
         foreach ($providers as $currentProviderId => $provider) {
             if ($provider instanceof ProviderServiceDiscoverInterface === false) {
@@ -469,23 +453,26 @@ class Manager {
      *
      * @param string $tenantId Tenant identifier
      * @param string|null $userId User identifier for context
-     * @param ResourceIdentifiers|null $targets Provider/service sources
+     * @param SourceSelector|null $sources Provider/service sources
      * @param IFilter|null $filter Collection filter
      * @param ISort|null $sort Collection sort
      *
      * @return array<string, array<string|int, array<string|int, ICollectionBase>>> Collections grouped by provider/service
      */
-    public function collectionList(string $tenantId, ?string $userId, ?ResourceIdentifiers $targets = null, ?IFilter $filter = null, ?ISort $sort = null): array {
+    public function collectionList(string $tenantId, ?string $userId, ?SourceSelector $sources = null, ?IFilter $filter = null, ?ISort $sort = null): array {
         // confirm that sources are provided
-        if ($targets === null) {
-            $targets = new ResourceIdentifiers([]);
+        if ($sources === null) {
+            $sources = new SourceSelector([]);
         }
         // retrieve providers
-        $aggregateServices = $this->serviceList($tenantId, $userId, $targets);
+        $providers = $this->providerList($tenantId, $userId, $sources);
         // retrieve services for each provider
         $responseData = [];
-        // retrieve collections for each service
-        foreach ($aggregateServices as $services) {
+        foreach ($providers as $provider) {
+            $serviceFilter = $sources[$provider->identifier()] instanceof ServiceSelector ? $sources[$provider->identifier()]->identifiers() : [];
+            /** @var ServiceBaseInterface[] $services */
+            $services = $provider->serviceList($tenantId, $userId, $serviceFilter);
+            // retrieve collections for each service
             foreach ($services as $service) {
                 if ($service->getEnabled() === false) {
                     continue;
@@ -506,23 +493,72 @@ class Manager {
                         $collectionSort->condition($attribute, $direction);
                     }
                 }
-
-                $collectionIdentifiers = $targets->byProvider($service->provider())->byService($service->identifier())->collections();
-                if ($collectionIdentifiers !== []) {
-                    foreach ($collectionIdentifiers as $collectionIdentifier) {
-                        $collections = array_merge($collections ?? [], $service->collectionList($collectionIdentifier, $collectionFilter, $collectionSort));
-                    }
-                } else {
-                    $collections = $service->collectionList('', $collectionFilter, $collectionSort);
-                }
+                $collections = $service->collectionList('', $collectionFilter, $collectionSort);
                 if ($collections !== []) {
-                    $responseData[$service->provider()][$service->identifier()] = $collections;
+                    $responseData[$provider->identifier()][$service->identifier()] = $collections;
                 }
             }
         }
         return $responseData;
     }
 
+    /**
+     * Check if collections exist
+     *
+     * @since 2025.05.01
+     *
+     * @param string $tenantId Tenant identifier
+     * @param string|null $userId User identifier for context
+     * @param SourceSelector $sources Collection sources with identifiers
+     *
+     * @return array<string, array<string|int, array<string|int, bool>>> Existence map grouped by provider/service
+     */
+    public function collectionExtant(string $tenantId, ?string $userId, SourceSelector $sources): array {
+        // retrieve available providers
+        $providers = $this->providerList($tenantId, $userId, $sources);
+        $providersRequested = $sources->identifiers();
+        $providersUnavailable = array_diff($providersRequested, array_keys($providers));
+        
+        // initialize response with unavailable providers
+        $responseData = array_fill_keys($providersUnavailable, false);
+        
+        // check services and collections for each available provider
+        foreach ($providers as $provider) {
+            // extract services for this provider
+            $serviceSelector = $sources[$provider->identifier()];
+            $servicesRequested = $serviceSelector->identifiers();
+            /** @var ServiceBaseInterface[] $servicesAvailable */
+            $servicesAvailable = $provider->serviceList($tenantId, $userId, $servicesRequested);
+            $servicesUnavailable = array_diff($servicesRequested, array_keys($servicesAvailable));
+            // mark unavailable services as false
+            if ($servicesUnavailable !== []) {
+                $responseData[$provider->identifier()] = array_fill_keys($servicesUnavailable, false);
+            }
+            // confirm collections for each available service
+            foreach ($servicesAvailable as $service) {
+                // omit disabled services
+                if ($service->getEnabled() === false) {
+                    $responseData[$provider->identifier()][$service->identifier()] = false;
+                    continue;
+                }
+                // extract collections requested for this service
+                $collectionSelector = $serviceSelector[$service->identifier()];
+                $collectionsRequested = $collectionSelector instanceof CollectionSelector ? $collectionSelector->identifiers() : [];
+                if ($collectionsRequested === []) {
+                    continue;
+                }
+                // check each requested collection
+                $collectionsAvailable = $service->collectionExtant(...$collectionsRequested);
+                $collectionsUnavailable = array_diff($collectionsRequested, array_keys($collectionsAvailable));
+                $responseData[$provider->identifier()][$service->identifier()] = array_merge(
+                    $collectionsAvailable,
+                    array_fill_keys($collectionsUnavailable, false)
+                );
+            }
+        }
+        return $responseData;
+    }
+
     /**
      * Fetch a specific collection
      *
@@ -536,62 +572,14 @@ class Manager {
      *
      * @return CollectionBaseInterface|null
      */
-    public function collectionFetch(string $tenantId, ?string $userId, CollectionIdentifier $target): ?CollectionBaseInterface {
+    public function collectionFetch(string $tenantId, ?string $userId, string $providerId, string|int $serviceId, string|int $collectionId): ?CollectionBaseInterface {
         // retrieve service
-        $service = $this->serviceFetch($tenantId, $userId, $target->provider(), $target->service());
-        // retrieve collection
-        return $service->collectionFetch($target->collection());
-    }
-
-    /**
-     * Check if collections exist
-     *
-     * @since 2025.05.01
-     *
-     * @param string $tenantId Tenant identifier
-     * @param string|null $userId User identifier for context
-     * @param ResourceIdentifiers $targets Collection sources with identifiers
-     *
-     * @return array<string, array<string|int, array<string|int, bool>>> Existence map grouped by provider/service
-     */
-    public function collectionExtant(string $tenantId, ?string $userId, ResourceIdentifiers $targets): array {
-        // retrieve available services grouped by provider
-        $aggregateServices = $this->serviceList($tenantId, $userId, $targets);
-        // initialize response with unavailable providers marked as false
-        $providersRequested = $targets->providers();
-        $providersUnavailable = array_diff($providersRequested, array_keys($aggregateServices));
-        $responseData = array_fill_keys($providersUnavailable, false);
-
-        // check services and collections for each available provider
-        foreach ($aggregateServices as $providerId => $services) {
-            // mark unavailable services as false
-            $servicesRequested = $targets->byProvider($providerId)->services();
-            $servicesUnavailable = array_diff($servicesRequested, array_keys($services));
-            if ($servicesUnavailable !== []) {
-                $responseData[$providerId] = array_fill_keys($servicesUnavailable, false);
-            }
-            // confirm collections for each available service
-            foreach ($services as $service) {
-                // omit disabled services
-                if ($service->getEnabled() === false) {
-                    $responseData[$providerId][$service->identifier()] = false;
-                    continue;
-                }
-                // extract collections requested for this service
-                $collectionsRequested = $targets->byProvider($providerId)->byService($service->identifier())->collections();
-                if ($collectionsRequested === []) {
-                    continue;
-                }
-                // check each requested collection
-                $collectionsAvailable = $service->collectionExtant(...$collectionsRequested);
-                $collectionsUnavailable = array_diff($collectionsRequested, array_keys($collectionsAvailable));
-                $responseData[$providerId][$service->identifier()] = array_merge(
-                    $collectionsAvailable,
-                    array_fill_keys($collectionsUnavailable, false)
-                );
-            }
+        $service = $this->serviceFetch($tenantId, $userId, $providerId, $serviceId);
+        if ($service === null || $service->getEnabled() === false) {
+            return null;
         }
-        return $responseData;
+        // retrieve collection
+        return $service->collectionFetch($collectionId);
     }
 
     /**
@@ -736,31 +724,31 @@ class Manager {
      *
      * @param string $tenantId Tenant identifier
      * @param string $userId User identifier
-     * @param ResourceIdentifiers|null $targets Message sources with collection identifiers
+     * @param SourceSelector $sources Message sources with collection identifiers
      * @param array|null $filter Message filter
      * @param array|null $sort Message sort
      * @param array|null $range Message range/pagination
      *
      * @return array<string, array<string|int, array<string|int, array<string|int, IMessageBase>>>> Messages grouped by provider/service/collection
      */
-    public function entityListBulk(string $tenantId, string $userId, ?ResourceIdentifiers $targets = null, array|null $filter = null, array|null $sort = null, array|null $range = null): array {
-        // confirm that sources are provided
-        if ($targets === null) {
-            $targets = new ResourceIdentifiers([]);
-        }
+    public function entityListBulk(string $tenantId, string $userId, SourceSelector $sources, array|null $filter = null, array|null $sort = null, array|null $range = null): array {
+        // retrieve providers
+        $providers = $this->providerList($tenantId, $userId, $sources);
         // retrieve services for each provider
-        $aggregateServices = $this->serviceList($tenantId, $userId, $targets);
-        // retrieve entities for each service
         $responseData = [];
-        foreach ($aggregateServices as $services) {
+        foreach ($providers as $provider) {
+            // retrieve services for each provider
+            $serviceSelector = $sources[$provider->identifier()];
+            $servicesSelected = $provider->serviceList($tenantId,$userId, $serviceSelector->identifiers());
             /** @var ServiceBaseInterface $service */
-            foreach ($services as $service) {
+            foreach ($servicesSelected as $service) {
                 // omit disabled services
                 if ($service->getEnabled() === false) {
                     continue;
                 }
 				// retrieve collections for each service
-				$collectionSelected = $targets->byProvider($service->provider())->byService($service->identifier())->collections();
+                $collectionSelector = $serviceSelector[$service->identifier()];
+				$collectionSelected = $collectionSelector instanceof CollectionSelector ? $collectionSelector->identifiers() : [];
 				if ($collectionSelected === []) {
 					$collections = $service->collectionList('');
 					$collectionSelected = array_map(
@@ -790,16 +778,29 @@ class Manager {
                 // construct range for entities
                 $entityRange = null;
                 if ($range !== null && $range !== [] && isset($range['type'])) {
-                    $entityRange = $service->entityListRange(RangeType::from($range['type']))->jsonDeserialize($range);
+                    $entityRange = $service->entityListRange(RangeType::from($range['type']));
+                    // Cast to IRangeTally if the range type is TALLY
+                    if ($entityRange->type() === RangeType::TALLY) {
+                        /** @var IRangeTally $entityRange */
+                        if (isset($range['anchor'])) {
+                            $entityRange->setAnchor(RangeAnchorType::from($range['anchor']));
+                        }
+                        if (isset($range['position'])) {
+                            $entityRange->setPosition($range['position']);
+                        }
+                        if (isset($range['tally'])) {
+                            $entityRange->setTally($range['tally']);
+                        }
+                    }
                 }
 				// retrieve entities for each collection
 				foreach ($collectionSelected as $collectionId) {
-					$entities = $service->entityListBulk($collectionId, $entityFilter, $entitySort, $entityRange, null);
+					$entities = $service->entityList($collectionId, $entityFilter, $entitySort, $entityRange, null);
 					// skip collections with no entities
 					if ($entities === []) {
 						continue;
 					}
-					$responseData[$service->provider()][$service->identifier()][$collectionId] = $entities;
+					$responseData[$provider->identifier()][$service->identifier()][$collectionId] = $entities;
 				}
 			}
         }
@@ -814,29 +815,29 @@ class Manager {
      *
      * @param string $tenantId Tenant identifier
      * @param string $userId User identifier
-     * @param ResourceIdentifiers|null $targets Message sources with collection identifiers
+     * @param SourceSelector $sources Message sources with collection identifiers
      * @param array|null $filter Message filter
      * @param array|null $sort Message sort
      * @param array|null $range Message range/pagination
      *
      * @return \Generator<EntityBaseInterface> Yields each entity as it is retrieved
      */
-    public function entityListStream(string $tenantId, string $userId, ?ResourceIdentifiers $targets = null, array|null $filter = null, array|null $sort = null, array|null $range = null): \Generator {
-        // confirm that sources are provided
-        if ($targets === null) {
-            $targets = new ResourceIdentifiers([]);
-        }
+    public function entityListStream(string $tenantId, string $userId, SourceSelector $sources, array|null $filter = null, array|null $sort = null, array|null $range = null): \Generator {
+        // retrieve providers
+        $providers = $this->providerList($tenantId, $userId, $sources);
         // retrieve services for each provider
-        $aggregateServices = $this->serviceList($tenantId, $userId, $targets);
-        foreach ($aggregateServices as $services) {
+        foreach ($providers as $provider) {
+            $serviceSelector = $sources[$provider->identifier()];
+            $servicesSelected = $provider->serviceList($tenantId, $userId, $serviceSelector->identifiers());
             /** @var ServiceBaseInterface $service */
-            foreach ($services as $service) {
+            foreach ($servicesSelected as $service) {
                 // omit disabled services
                 if ($service->getEnabled() === false) {
                     continue;
                 }
                 // retrieve collections for each service
-                $collectionSelected = $targets->byProvider($service->provider())->byService($service->identifier())->collections();
+                $collectionSelector = $serviceSelector[$service->identifier()];
+                $collectionSelected = $collectionSelector instanceof CollectionSelector ? $collectionSelector->identifiers() : [];
                 if ($collectionSelected === []) {
                     $collections = $service->collectionList('');
                     $collectionSelected = array_map(
@@ -866,7 +867,19 @@ class Manager {
                 // construct range for entities
                 $entityRange = null;
                 if ($range !== null && $range !== [] && isset($range['type'])) {
-                    $entityRange = $service->entityListRange(RangeType::from($range['type']))->jsonDeserialize($range);
+                    $entityRange = $service->entityListRange(RangeType::from($range['type']));
+                    if ($entityRange->type() === RangeType::TALLY) {
+                        /** @var IRangeTally $entityRange */
+                        if (isset($range['anchor'])) {
+                            $entityRange->setAnchor(RangeAnchorType::from($range['anchor']));
+                        }
+                        if (isset($range['position'])) {
+                            $entityRange->setPosition($range['position']);
+                        }
+                        if (isset($range['tally'])) {
+                            $entityRange->setTally($range['tally']);
+                        }
+                    }
                 }
                 // yield entities for each collection individually
                 foreach ($collectionSelected as $collectionId) {
@@ -891,7 +904,7 @@ class Manager {
         // group identifiers by provider/service
         $groupedIdentifiers = [];
         foreach ($identifiers as $identifier) {
-            $groupedIdentifiers[$identifier->provider()][$identifier->service()][] = $identifier;
+            $groupedIdentifiers[$identifier->provider()][$identifier->service()][] = $identifier->entity();
         }
         // retrieve each service and fetch entities
         $list = [];
@@ -945,36 +958,43 @@ class Manager {
      *
      * @param string $tenantId Tenant identifier
      * @param string|null $userId User identifier for context
-     * @param ResourceIdentifiers $targets Message sources with identifiers
+     * @param SourceSelector $sources Message sources with identifiers
      *
      * @return array<string, array<string|int, array<string|int, array<string|int, bool>>>> Existence map grouped by provider/service/collection
      */
-    public function entityExtant(string $tenantId, string $userId, ResourceIdentifiers $targets): array {
-        // retrieve available services grouped by provider
-        $aggregateServices = $this->serviceList($tenantId, $userId, $targets);
-        // initialize response with unavailable providers marked as false
-        $providersRequested = $targets->providers();
-        $providersUnavailable = array_diff($providersRequested, array_keys($aggregateServices));
+    public function entityExtant(string $tenantId, string $userId, SourceSelector $sources): array {
+        // confirm that sources are provided
+        if ($sources === null) {
+            $sources = new SourceSelector([]);
+        }
+        // retrieve available providers
+        $providers = $this->providerList($tenantId, $userId, $sources);
+        $providersRequested = $sources->identifiers();
+        $providersUnavailable = array_diff($providersRequested, array_keys($providers));
+        // initialize response with unavailable providers
         $responseData = array_fill_keys($providersUnavailable, false);
-
         // check services, collections, and entities for each available provider
-        foreach ($aggregateServices as $providerId => $services) {
+        foreach ($providers as $provider) {
+            // extract services requested for this provider
+            $serviceSelector = $sources[$provider->identifier()];
+            $servicesRequested = $serviceSelector->identifiers();
+            /** @var ServiceBaseInterface[] $servicesAvailable */
+            $servicesAvailable = $provider->serviceList($tenantId, $userId, $servicesRequested);
+            $servicesUnavailable = array_diff($servicesRequested, array_keys($servicesAvailable));
             // mark unavailable services as false
-            $servicesRequested = $targets->byProvider($providerId)->services();
-            $servicesUnavailable = array_diff($servicesRequested, array_keys($services));
             if ($servicesUnavailable !== []) {
-                $responseData[$providerId] = array_fill_keys($servicesUnavailable, false);
+                $responseData[$provider->identifier()] = array_fill_keys($servicesUnavailable, false);
             }
             // check collections and entities for each available service
-            foreach ($services as $service) {
+            foreach ($servicesAvailable as $service) {
                 // omit disabled services
                 if ($service->getEnabled() === false) {
-                    $responseData[$providerId][$service->identifier()] = false;
+                    $responseData[$provider->identifier()][$service->identifier()] = false;
                     continue;
                 }
                 // extract collections requested for this service
-                $serviceTargets = $targets->byProvider($providerId)->byService($service->identifier());
-                $collectionsRequested = $serviceTargets->collections();
+                $collectionSelector = $serviceSelector[$service->identifier()];
+                $collectionsRequested = $collectionSelector instanceof CollectionSelector ? $collectionSelector->identifiers() : [];
                 if ($collectionsRequested === []) {
                     continue;
                 }
@@ -984,18 +1004,19 @@ class Manager {
                     $collectionExists = $service->collectionExtant((string)$collectionId);
                     if (!$collectionExists) {
                         // collection doesn't exist, mark as false
-                        $responseData[$providerId][$service->identifier()][$collectionId] = false;
+                        $responseData[$provider->identifier()][$service->identifier()][$collectionId] = false;
                         continue;
                     }
-                    // extract entity identifiers requested for this collection
-                    $entitiesRequested = $serviceTargets->byCollection($collectionId)->entities();
-                    if ($entitiesRequested === []) {
+                    // extract entity identifiers from collection selector
+                    $entitySelector = $collectionSelector[$collectionId];
+                    // handle both array of entity IDs and boolean true (meaning check if collection exists)
+                    if ($entitySelector instanceof EntitySelector) {
+                        // check specific entities within the collection
+                        $responseData[$provider->identifier()][$service->identifier()][$collectionId] = $service->entityExtant($collectionId, ...$entitySelector->identifiers());
+                    } elseif ($entitySelector === true) {
                         // just checking if collection exists (already confirmed above)
-                        $responseData[$providerId][$service->identifier()][$collectionId] = true;
-                        continue;
+                        $responseData[$provider->identifier()][$service->identifier()][$collectionId] = true;
                     }
-                    // check specific entities within the collection
-                    $responseData[$providerId][$service->identifier()][$collectionId] = $service->entityExtant($collectionId, ...$entitiesRequested);
                 }
             }
         }
@@ -1009,45 +1030,50 @@ class Manager {
      *
      * @param string $tenantId Tenant identifier
      * @param string|null $userId User identifier for context
-     * @param ResourceIdentifiers $targets Message sources with signatures
+     * @param SourceSelector $sources Message sources with signatures
      *
      * @return array<string, array<string|int, array<string|int, array>>> Delta grouped by provider/service/collection
      */
-    public function entityDelta(string $tenantId, string $userId, ResourceIdentifiers $targets): array {
-        // retrieve available services grouped by provider
-        $aggregateServices = $this->serviceList($tenantId, $userId, $targets);
-        // initialize response with unavailable providers marked as false
-        $providersRequested = $targets->providers();
-        $providersUnavailable = array_diff($providersRequested, array_keys($aggregateServices));
+    public function entityDelta(string $tenantId, string $userId, SourceSelector $sources): array {
+        // confirm that sources are provided
+        if ($sources === null) {
+            $sources = new SourceSelector([]);
+        }
+        // retrieve providers
+        $providers = $this->providerList($tenantId, $userId, $sources);
+        $providersRequested = $sources->identifiers();
+        $providersUnavailable = array_diff($providersRequested, array_keys($providers));
+        // initialize response with unavailable providers
         $responseData = array_fill_keys($providersUnavailable, false);
-
         // iterate through available providers
-        foreach ($aggregateServices as $providerId => $services) {
-            // mark unavailable services as false
-            $servicesRequested = $targets->byProvider($providerId)->services();
+        foreach ($providers as $provider) {
+            // extract services requested for this provider
+            $serviceSelector = $sources[$provider->identifier()];
+            $servicesRequested = $serviceSelector instanceof ServiceSelector ? $serviceSelector->identifiers() : [];
+            /** @var ServiceBaseInterface[] $services */
+            $services = $provider->serviceList($tenantId, $userId, $servicesRequested);
             $servicesUnavailable = array_diff($servicesRequested, array_keys($services));
             if ($servicesUnavailable !== []) {
-                $responseData[$providerId] = array_fill_keys($servicesUnavailable, false);
+                $responseData[$provider->identifier()] = array_fill_keys($servicesUnavailable, false);
             }
             // iterate through available services
             foreach ($services as $service) {
                 // omit disabled services
                 if ($service->getEnabled() === false) {
-                    $responseData[$providerId][$service->identifier()] = false;
+                    $responseData[$provider->identifier()][$service->identifier()] = false;
                     continue;
                 }
                 // extract collections requested for this service
-                $serviceTargets = $targets->byProvider($providerId)->byService($service->identifier());
-                $collectionsRequested = $serviceTargets->collections();
+                $collectionSelector = $serviceSelector[$service->identifier()];
+                $collectionsRequested = $collectionSelector instanceof CollectionSelector ? $collectionSelector->identifiers() : [];
                 if ($collectionsRequested === []) {
-                    $responseData[$providerId][$service->identifier()] = false;
+                    $responseData[$provider->identifier()][$service->identifier()] = false;
                     continue;
                 }
                 // check delta for each requested collection
                 foreach ($collectionsRequested as $collection) {
-                    // signature for the collection is carried in the entity slot of the identifier
-                    $signature = $serviceTargets->byCollection($collection)->entities()[0] ?? '';
-                    $responseData[$providerId][$service->identifier()][$collection] = $service->entityDelta($collection, $signature);
+                    $entitySelector = $collectionSelector[$collection] ?? null;
+                    $responseData[$provider->identifier()][$service->identifier()][$collection] = $service->entityDelta($collection, $entitySelector);
                 }
             }
         }
@@ -1127,63 +1153,6 @@ class Manager {
         return $operationOutcome;
     }
 
-    /**
-     * Create a new entity in a collection.
-     *
-     * @param MessagePropertiesMutableInterface|array $properties Entity properties
-     *
-     * @throws InvalidArgumentException
-     */
-    public function entityCreate(string $tenantId, string $userId, CollectionIdentifier $target, MessagePropertiesMutableInterface|array $properties, array $options = []): EntityBaseInterface
-    {
-        $service = $this->serviceFetch($tenantId, $userId, $target->provider(), $target->service());
-
-        if ($service->getEnabled() === false) {
-            throw new InvalidArgumentException("Service '{$service->identifier()}' not found or is disabled");
-        }
-        if ($service instanceof ServiceEntityMutableInterface === false) {
-            throw new InvalidArgumentException("Service '{$service->identifier()}' does not support entity mutations");
-        }
-        if (!$service->capable(ServiceEntityMutableInterface::CAPABILITY_ENTITY_CREATE)) {
-            throw new InvalidArgumentException("Service '{$service->identifier()}' is not capable of creating entities");
-        }
-        if ($properties instanceof MessagePropertiesMutableInterface === false) {
-            $properties = $service->entityFresh()->getProperties()->jsonDeserialize($properties);
-        }
-
-        return $service->entityCreate($target, $properties, $options);
-    }
-
-    /**
-     * Modify an existing entity.
-     *
-     * The returned entity identifier is authoritative and may differ from the
-     * target identifier for providers that use replacement semantics.
-     *
-     * @param MessagePropertiesMutableInterface|array $properties Entity properties
-     *
-     * @throws InvalidArgumentException
-     */
-    public function entityModify(string $tenantId, string $userId, EntityIdentifier $target, MessagePropertiesMutableInterface|array $properties): EntityBaseInterface
-    {
-        $service = $this->serviceFetch($tenantId, $userId, $target->provider(), $target->service());
-
-        if ($service->getEnabled() === false) {
-            throw new InvalidArgumentException("Service '{$service->identifier()}' not found or is disabled");
-        }
-        if ($service instanceof ServiceEntityMutableInterface === false) {
-            throw new InvalidArgumentException("Service '{$service->identifier()}' does not support entity mutations");
-        }
-        if (!$service->capable(ServiceEntityMutableInterface::CAPABILITY_ENTITY_MODIFY)) {
-            throw new InvalidArgumentException("Service '{$service->identifier()}' is not capable of modifying entities");
-        }
-        if ($properties instanceof MessagePropertiesMutableInterface === false) {
-            $properties = $service->entityFresh()->getProperties()->jsonDeserialize($properties);
-        }
-
-        return $service->entityModify($target, $properties);
-    }
-
     /**
      * Deletes entities
      *
@@ -1325,74 +1294,5 @@ class Manager {
         return $operationOutcome;
     }
 
-    public function entitySubmit(string $tenantId, string $userId, AddressInterface|string $sender, EntityIdentifierInterface|null $source = null, MessagePropertiesMutableInterface|array|null $message = null): EntitySubmitResult {
-        if ($sender instanceof AddressInterface === false) {
-            $sender = new Address($sender);
-        }
-
-        $service = $this->serviceFindByAddress($tenantId, $userId, $sender->getAddress());
-        if ($service === null || $service->getEnabled() === false) {
-            throw new InvalidArgumentException("Service not found for sender '{$sender->getAddress()}' or service is disabled");
-        }
-        if ($service instanceof ServiceEntitySubmitInterface === false) {
-            throw new InvalidArgumentException("Service '{$service->identifier()}' does not support entity submission");
-        }
-
-        if ($source === null && $message === null) {
-            throw new InvalidArgumentException("At least one of source or message must be provided for entity submission");
-        }
-
-        if ($message !== null && $message instanceof MessagePropertiesMutableInterface === false) {
-            $message = $service->entityFresh()->getProperties()->jsonDeserialize($message);
-        }
-
-        return $service->entitySubmit($sender, $source, $message);
-    }
-
-    public function entityDownload(string $tenantId, string $userId, EntityIdentifier $targetEntity, array|null $targetPart): BinaryResource {
-        // retrieve service
-        $service = $this->serviceFetch($tenantId, $userId, $targetEntity->provider(), $targetEntity->service());
-        // download entity
-        return $service->entityDownload($targetEntity, $targetPart);
-    }
-
-    /**
-     * Resolve an authorized attachment and lazily generate or retrieve its preview.
-     */
-    public function entityPreview(string $tenantId, string $userId, EntityIdentifier $targetEntity, array $part, string $variant = 'inline'): ?Preview {
-        $mimeType = $part['type'] ?? null;
-        $size = $part['size'] ?? null;
-        if (!is_string($mimeType) || ($size !== null && !is_int($size))) {
-            throw new InvalidArgumentException('Attachment preview requires a MIME type and optional integer size');
-        }
-
-        $selector = array_filter([
-            'blobId' => $part['blobId'] ?? null,
-            'partId' => $part['partId'] ?? null,
-            'cid' => $part['cid'] ?? null,
-        ], static fn(mixed $value): bool => is_string($value) && $value !== '');
-        if ($selector === []) {
-            throw new InvalidArgumentException('Attachment preview requires a blob, part, or content identifier');
-        }
-
-        $attachmentIdentity = hash('sha256', json_encode($selector, JSON_THROW_ON_ERROR));
-
-        return $this->previewManager->fetch($tenantId, new PreviewSource(
-            sourceType: 'mail-attachment',
-            identity: (string) $targetEntity . ':' . $attachmentIdentity,
-            // Attachments are immutable once delivered, so there is no revision to track;
-            // existence and access are enforced by entityDownload() (via serviceFetch) below,
-            // which only runs on a cache miss.
-            signature: 'immutable',
-            mimeType: $mimeType,
-            size: $size,
-            resourceFactory: fn(): BinaryResource => $this->entityDownload(
-                $tenantId,
-                $userId,
-                $targetEntity,
-                $selector,
-            ),
-        ), $variant);
-    }
 
 }

lib/Module.php

@@ -2,8 +2,7 @@
 
 namespace KTXM\MailManager;
 
-use KTXF\Module\Configuration\BrowserModuleContextInterface;
-use KTXF\Module\Configuration\ModuleContextInterface;
+use KTXF\Module\ModuleBrowserInterface;
 use KTXF\Module\ModuleInstanceAbstract;
 
 /**
@@ -12,7 +11,7 @@ use KTXF\Module\ModuleInstanceAbstract;
  * Provides unified mail sending and management across multiple providers
  * with context-aware service discovery and queued delivery.
  */
-class Module extends ModuleInstanceAbstract
+class Module extends ModuleInstanceAbstract implements ModuleBrowserInterface
 {
 
     public function __construct()
@@ -51,18 +50,18 @@ class Module extends ModuleInstanceAbstract
                 'description' => 'View and access the mail manager module',
                 'group' => 'Mail Management'
             ],
-            'mail_manager.system' => [
-                'label' => 'Manage System Mail',
-                'description' => 'Manage system mail accounts and routing rules (act in the reserved system user context)',
-                'group' => 'Mail Management'
-            ],
         ];
     }
     
-    public function configure(ModuleContextInterface $context): void
-    {
-        if ($context instanceof BrowserModuleContextInterface) {
-            $context->registerModule($this, 'MailManager', 'static/module.mjs');
-        }
+    public function registerBI(): array {
+        return [
+            'handle' => $this->handle(),
+            'namespace' => 'MailManager',
+            'version' => $this->version(),
+            'label' => $this->label(),
+            'author' => $this->author(),
+            'description' => $this->description(),
+            'boot' => 'static/module.mjs',
+        ];
     }
 }

lib/Queue/JobStatus.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXM\MailManager\Queue;
+
+use JsonSerializable;
+
+/**
+ * Mail Job Status
+ * 
+ * Status states for queued mail jobs.
+ * 
+ * @since 2025.05.01
+ */
+enum JobStatus: string implements JsonSerializable {
+
+    case Pending = 'pending';
+    case Processing = 'processing';
+    case Complete = 'complete';
+    case Failed = 'failed';
+
+    public function jsonSerialize(): string {
+        return $this->value;
+    }
+
+}

lib/Queue/MailJob.php

@@ -0,0 +1,115 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXM\MailManager\Queue;
+
+use DateTimeImmutable;
+use KTXF\Mail\Entity\IMessageMutable;
+use KTXF\Mail\Queue\SendOptions;
+
+/**
+ * Mail Job
+ * 
+ * Represents a queued mail job with metadata and message content.
+ * 
+ * @since 2025.05.01
+ */
+class MailJob {
+
+    public function __construct(
+        public readonly string $id,
+        public readonly string $tenantId,
+        public readonly string $providerId,
+        public readonly string|int $serviceId,
+        public readonly IMessageMutable $message,
+        public readonly SendOptions $options,
+        public JobStatus $status = JobStatus::Pending,
+        public int $attempts = 0,
+        public ?string $lastError = null,
+        public ?string $messageId = null,
+        public ?DateTimeImmutable $created = null,
+        public ?DateTimeImmutable $scheduled = null,
+        public ?DateTimeImmutable $lastAttempt = null,
+        public ?DateTimeImmutable $completed = null,
+    ) {
+        $this->created = $this->created ?? new DateTimeImmutable();
+        $this->scheduled = $this->scheduled ?? $this->calculateScheduledTime();
+    }
+
+    /**
+     * Calculate when this job should be processed
+     * 
+     * @return DateTimeImmutable
+     */
+    private function calculateScheduledTime(): DateTimeImmutable {
+        $scheduled = $this->created ?? new DateTimeImmutable();
+        
+        if ($this->options->delaySeconds !== null && $this->options->delaySeconds > 0) {
+            $scheduled = $scheduled->modify("+{$this->options->delaySeconds} seconds");
+        }
+        
+        return $scheduled;
+    }
+
+    /**
+     * Check if the job is ready to be processed
+     * 
+     * @return bool
+     */
+    public function isReady(): bool {
+        if ($this->status !== JobStatus::Pending) {
+            return false;
+        }
+        
+        return $this->scheduled === null || $this->scheduled <= new DateTimeImmutable();
+    }
+
+    /**
+     * Check if the job can be retried
+     * 
+     * @return bool
+     */
+    public function canRetry(): bool {
+        return $this->attempts < $this->options->retryCount;
+    }
+
+    /**
+     * Get retry delay in seconds based on attempt count (exponential backoff)
+     * 
+     * @return int
+     */
+    public function getRetryDelay(): int {
+        // Exponential backoff: 30s, 60s, 120s, 240s, ...
+        return min(30 * (2 ** $this->attempts), 3600);
+    }
+
+    /**
+     * Serialize job metadata for storage
+     * 
+     * @return array
+     */
+    public function toMetaArray(): array {
+        return [
+            'id' => $this->id,
+            'tenantId' => $this->tenantId,
+            'providerId' => $this->providerId,
+            'serviceId' => $this->serviceId,
+            'options' => $this->options->jsonSerialize(),
+            'status' => $this->status->value,
+            'attempts' => $this->attempts,
+            'lastError' => $this->lastError,
+            'messageId' => $this->messageId,
+            'created' => $this->created?->format('c'),
+            'scheduled' => $this->scheduled?->format('c'),
+            'lastAttempt' => $this->lastAttempt?->format('c'),
+            'completed' => $this->completed?->format('c'),
+        ];
+    }
+
+}

lib/Queue/MailQueueFile.php

@@ -0,0 +1,492 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXM\MailManager\Queue;
+
+use DateTimeImmutable;
+use DI\Attribute\Inject;
+use Psr\Log\LoggerInterface;
+use KTXF\Mail\Entity\IMessageMutable;
+use KTXF\Mail\Entity\Message;
+use KTXF\Mail\Queue\SendOptions;
+use RuntimeException;
+
+/**
+ * File-Based Mail Queue
+ * 
+ * Stores mail queue jobs on disk with atomic operations using file locks.
+ * 
+ * Structure:
+ *   storage/{tenantId}/mail/queue/
+ *     pending/{jobId}/
+ *       meta.json
+ *       message.json
+ *     processing/{jobId}/...
+ *     complete/{jobId}/...
+ *     failed/{jobId}/...
+ * 
+ * @since 2025.05.01
+ */
+class MailQueueFile {
+
+    private const DIR_PENDING = 'pending';
+    private const DIR_PROCESSING = 'processing';
+    private const DIR_COMPLETE = 'complete';
+    private const DIR_FAILED = 'failed';
+    private string $storagePath;
+
+    public function __construct(
+        private LoggerInterface $logger,
+        #[Inject('rootDir')] private readonly string $rootDir,
+    ) {
+        $this->storagePath = $this->rootDir . '/var/cache/mail_manager/queue';
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function enqueue(
+        string $tenantId,
+        string $providerId,
+        string|int $serviceId,
+        IMessageMutable $message,
+        SendOptions $options
+    ): string {
+        $jobId = $this->generateJobId();
+        
+        $job = new MailJob(
+            id: $jobId,
+            tenantId: $tenantId,
+            providerId: $providerId,
+            serviceId: $serviceId,
+            message: $message,
+            options: $options,
+        );
+        
+        $this->writeJob($job, self::DIR_PENDING);
+        
+        return $jobId;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function dequeue(string $tenantId, int $limit = 50): array {
+        $pendingDir = $this->getQueueDir($tenantId, self::DIR_PENDING);
+        
+        if (!is_dir($pendingDir)) {
+            return [];
+        }
+        
+        $jobs = [];
+        $entries = scandir($pendingDir);
+        
+        // Sort by priority (read meta files)
+        $jobsWithPriority = [];
+        foreach ($entries as $entry) {
+            if ($entry === '.' || $entry === '..') {
+                continue;
+            }
+            
+            $jobDir = $pendingDir . '/' . $entry;
+            if (!is_dir($jobDir)) {
+                continue;
+            }
+            
+            $metaFile = $jobDir . '/meta.json';
+            if (!file_exists($metaFile)) {
+                continue;
+            }
+            
+            $meta = json_decode(file_get_contents($metaFile), true);
+            if ($meta === null) {
+                continue;
+            }
+            
+            $scheduled = isset($meta['scheduled']) ? new DateTimeImmutable($meta['scheduled']) : null;
+            if ($scheduled !== null && $scheduled > new DateTimeImmutable()) {
+                continue; // Not ready yet
+            }
+            
+            $jobsWithPriority[] = [
+                'id' => $entry,
+                'priority' => $meta['options']['priority'] ?? 0,
+                'created' => $meta['created'] ?? '',
+            ];
+        }
+        
+        // Sort by priority (desc) then by created (asc)
+        usort($jobsWithPriority, function($a, $b) {
+            if ($a['priority'] !== $b['priority']) {
+                return $b['priority'] <=> $a['priority'];
+            }
+            return $a['created'] <=> $b['created'];
+        });
+        
+        // Take up to limit and move to processing
+        $jobsWithPriority = array_slice($jobsWithPriority, 0, $limit);
+        
+        foreach ($jobsWithPriority as $jobInfo) {
+            $job = $this->loadJob($tenantId, $jobInfo['id'], self::DIR_PENDING);
+            if ($job === null) {
+                continue;
+            }
+            
+            // Move to processing
+            $this->moveJob($tenantId, $jobInfo['id'], self::DIR_PENDING, self::DIR_PROCESSING);
+            $job->status = JobStatus::Processing;
+            $job->lastAttempt = new DateTimeImmutable();
+            $job->attempts++;
+            $this->updateJobMeta($tenantId, $jobInfo['id'], $job, self::DIR_PROCESSING);
+            
+            $jobs[] = $job;
+        }
+        
+        return $jobs;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function acknowledge(string $jobId, string $messageId): void {
+        $job = $this->findJobById($jobId);
+        if ($job === null) {
+            return;
+        }
+        
+        $job->status = JobStatus::Complete;
+        $job->messageId = $messageId;
+        $job->completed = new DateTimeImmutable();
+        
+        $this->moveJob($job->tenantId, $jobId, self::DIR_PROCESSING, self::DIR_COMPLETE);
+        $this->updateJobMeta($job->tenantId, $jobId, $job, self::DIR_COMPLETE);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function reject(string $jobId, string $error, bool $retry = true): void {
+        $job = $this->findJobById($jobId);
+        if ($job === null) {
+            return;
+        }
+        
+        $job->lastError = $error;
+        
+        if ($retry && $job->canRetry()) {
+            // Move back to pending with delay
+            $job->status = JobStatus::Pending;
+            $job->scheduled = (new DateTimeImmutable())->modify('+' . $job->getRetryDelay() . ' seconds');
+            
+            $this->moveJob($job->tenantId, $jobId, self::DIR_PROCESSING, self::DIR_PENDING);
+            $this->updateJobMeta($job->tenantId, $jobId, $job, self::DIR_PENDING);
+        } else {
+            // Move to failed
+            $job->status = JobStatus::Failed;
+            $job->completed = new DateTimeImmutable();
+            
+            $this->moveJob($job->tenantId, $jobId, self::DIR_PROCESSING, self::DIR_FAILED);
+            $this->updateJobMeta($job->tenantId, $jobId, $job, self::DIR_FAILED);
+        }
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getJob(string $jobId): ?MailJob {
+        return $this->findJobById($jobId);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function listJobs(string $tenantId, ?JobStatus $status = null, int $limit = 100, int $offset = 0): array {
+        $dirs = $status !== null 
+            ? [$this->statusToDir($status)]
+            : [self::DIR_PENDING, self::DIR_PROCESSING, self::DIR_COMPLETE, self::DIR_FAILED];
+        
+        $jobs = [];
+        
+        foreach ($dirs as $dir) {
+            $queueDir = $this->getQueueDir($tenantId, $dir);
+            if (!is_dir($queueDir)) {
+                continue;
+            }
+            
+            foreach (scandir($queueDir) as $entry) {
+                if ($entry === '.' || $entry === '..') {
+                    continue;
+                }
+                
+                $job = $this->loadJob($tenantId, $entry, $dir);
+                if ($job !== null) {
+                    $jobs[] = $job;
+                }
+            }
+        }
+        
+        // Sort by created desc
+        usort($jobs, fn($a, $b) => ($b->created?->getTimestamp() ?? 0) <=> ($a->created?->getTimestamp() ?? 0));
+        
+        return array_slice($jobs, $offset, $limit);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function retry(string $jobId): bool {
+        $job = $this->findJobById($jobId);
+        if ($job === null || $job->status !== JobStatus::Failed) {
+            return false;
+        }
+        
+        $job->status = JobStatus::Pending;
+        $job->attempts = 0;
+        $job->lastError = null;
+        $job->scheduled = new DateTimeImmutable();
+        
+        $this->moveJob($job->tenantId, $jobId, self::DIR_FAILED, self::DIR_PENDING);
+        $this->updateJobMeta($job->tenantId, $jobId, $job, self::DIR_PENDING);
+        
+        return true;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function purge(string $tenantId, JobStatus $status, int $olderThanSeconds): int {
+        $dir = $this->statusToDir($status);
+        $queueDir = $this->getQueueDir($tenantId, $dir);
+        
+        if (!is_dir($queueDir)) {
+            return 0;
+        }
+        
+        $threshold = new DateTimeImmutable("-{$olderThanSeconds} seconds");
+        $purged = 0;
+        
+        foreach (scandir($queueDir) as $entry) {
+            if ($entry === '.' || $entry === '..') {
+                continue;
+            }
+            
+            $jobDir = $queueDir . '/' . $entry;
+            $metaFile = $jobDir . '/meta.json';
+            
+            if (!file_exists($metaFile)) {
+                continue;
+            }
+            
+            $meta = json_decode(file_get_contents($metaFile), true);
+            $completed = isset($meta['completed']) ? new DateTimeImmutable($meta['completed']) : null;
+            
+            if ($completed !== null && $completed < $threshold) {
+                $this->deleteJobDir($jobDir);
+                $purged++;
+            }
+        }
+        
+        return $purged;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function stats(string $tenantId): array {
+        $stats = [
+            'pending' => 0,
+            'processing' => 0,
+            'complete' => 0,
+            'failed' => 0,
+        ];
+        
+        foreach ($stats as $status => $_) {
+            $dir = $this->getQueueDir($tenantId, $status);
+            if (is_dir($dir)) {
+                $stats[$status] = count(array_filter(
+                    scandir($dir),
+                    fn($e) => $e !== '.' && $e !== '..'
+                ));
+            }
+        }
+        
+        return $stats;
+    }
+
+    /**
+     * Generate a unique job ID
+     */
+    private function generateJobId(): string {
+        return sprintf(
+            '%08x-%04x-%04x-%04x-%012x',
+            time(),
+            mt_rand(0, 0xffff),
+            mt_rand(0, 0x0fff) | 0x4000,
+            mt_rand(0, 0x3fff) | 0x8000,
+            mt_rand(0, 0xffffffffffff)
+        );
+    }
+
+    /**
+     * Get the queue directory path for a tenant and status
+     */
+    private function getQueueDir(string $tenantId, string $status): string {
+        return $this->storagePath . '/' . $tenantId . '/mail/queue/' . $status;
+    }
+
+    /**
+     * Write a job to disk
+     */
+    private function writeJob(MailJob $job, string $status): void {
+        $jobDir = $this->getQueueDir($job->tenantId, $status) . '/' . $job->id;
+        
+        if (!is_dir($jobDir)) {
+            mkdir($jobDir, 0755, true);
+        }
+        
+        // Write meta
+        $metaFile = $jobDir . '/meta.json';
+        file_put_contents($metaFile, json_encode($job->toMetaArray(), JSON_PRETTY_PRINT));
+        
+        // Write message
+        $messageFile = $jobDir . '/message.json';
+        file_put_contents($messageFile, json_encode($job->message, JSON_PRETTY_PRINT));
+    }
+
+    /**
+     * Load a job from disk
+     */
+    private function loadJob(string $tenantId, string $jobId, string $status): ?MailJob {
+        $jobDir = $this->getQueueDir($tenantId, $status) . '/' . $jobId;
+        $metaFile = $jobDir . '/meta.json';
+        $messageFile = $jobDir . '/message.json';
+        
+        if (!file_exists($metaFile) || !file_exists($messageFile)) {
+            return null;
+        }
+        
+        $meta = json_decode(file_get_contents($metaFile), true);
+        $messageData = json_decode(file_get_contents($messageFile), true);
+        
+        if ($meta === null || $messageData === null) {
+            return null;
+        }
+        
+        $message = Message::fromArray($messageData);
+        
+        return new MailJob(
+            id: $meta['id'],
+            tenantId: $meta['tenantId'],
+            providerId: $meta['providerId'],
+            serviceId: $meta['serviceId'],
+            message: $message,
+            options: new SendOptions(
+                immediate: $meta['options']['immediate'] ?? false,
+                priority: $meta['options']['priority'] ?? 0,
+                retryCount: $meta['options']['retryCount'] ?? 3,
+                delaySeconds: $meta['options']['delaySeconds'] ?? null,
+            ),
+            status: JobStatus::from($meta['status']),
+            attempts: $meta['attempts'] ?? 0,
+            lastError: $meta['lastError'] ?? null,
+            messageId: $meta['messageId'] ?? null,
+            created: isset($meta['created']) ? new DateTimeImmutable($meta['created']) : null,
+            scheduled: isset($meta['scheduled']) ? new DateTimeImmutable($meta['scheduled']) : null,
+            lastAttempt: isset($meta['lastAttempt']) ? new DateTimeImmutable($meta['lastAttempt']) : null,
+            completed: isset($meta['completed']) ? new DateTimeImmutable($meta['completed']) : null,
+        );
+    }
+
+    /**
+     * Move a job between status directories
+     */
+    private function moveJob(string $tenantId, string $jobId, string $fromStatus, string $toStatus): void {
+        $fromDir = $this->getQueueDir($tenantId, $fromStatus) . '/' . $jobId;
+        $toDir = $this->getQueueDir($tenantId, $toStatus) . '/' . $jobId;
+        
+        if (!is_dir($fromDir)) {
+            throw new RuntimeException("Job directory not found: $fromDir");
+        }
+        
+        $toParent = dirname($toDir);
+        if (!is_dir($toParent)) {
+            mkdir($toParent, 0755, true);
+        }
+        
+        rename($fromDir, $toDir);
+    }
+
+    /**
+     * Update job metadata
+     */
+    private function updateJobMeta(string $tenantId, string $jobId, MailJob $job, string $status): void {
+        $metaFile = $this->getQueueDir($tenantId, $status) . '/' . $jobId . '/meta.json';
+        file_put_contents($metaFile, json_encode($job->toMetaArray(), JSON_PRETTY_PRINT));
+    }
+
+    /**
+     * Find a job by ID across all status directories
+     */
+    private function findJobById(string $jobId): ?MailJob {
+        // We need to search across all tenants and statuses
+        // This is inefficient - in production, consider caching or indexing
+        $tenantsDir = $this->storagePath;
+        
+        if (!is_dir($tenantsDir)) {
+            return null;
+        }
+        
+        foreach (scandir($tenantsDir) as $tenantId) {
+            if ($tenantId === '.' || $tenantId === '..') {
+                continue;
+            }
+            
+            foreach ([self::DIR_PENDING, self::DIR_PROCESSING, self::DIR_COMPLETE, self::DIR_FAILED] as $status) {
+                $job = $this->loadJob($tenantId, $jobId, $status);
+                if ($job !== null) {
+                    return $job;
+                }
+            }
+        }
+        
+        return null;
+    }
+
+    /**
+     * Delete a job directory recursively
+     */
+    private function deleteJobDir(string $dir): void {
+        if (!is_dir($dir)) {
+            return;
+        }
+        
+        foreach (scandir($dir) as $file) {
+            if ($file === '.' || $file === '..') {
+                continue;
+            }
+            $path = $dir . '/' . $file;
+            is_dir($path) ? $this->deleteJobDir($path) : unlink($path);
+        }
+        
+        rmdir($dir);
+    }
+
+    /**
+     * Convert JobStatus to directory name
+     */
+    private function statusToDir(JobStatus $status): string {
+        return match($status) {
+            JobStatus::Pending => self::DIR_PENDING,
+            JobStatus::Processing => self::DIR_PROCESSING,
+            JobStatus::Complete => self::DIR_COMPLETE,
+            JobStatus::Failed => self::DIR_FAILED,
+        };
+    }
+
+}

package.json

@@ -18,21 +18,18 @@
     "test:coverage": "vitest run --coverage --config tests/js/vitest.config.ts"
   },
   "dependencies": {
-    "pinia": "^4.0.0",
+    "pinia": "^2.3.1",
     "vue": "^3.5.18",
-    "vue-router": "^5.2.0",
+    "vue-router": "^5.0.0",
     "vuetify": "^4.0.0"
   },
   "devDependencies": {
     "@vitejs/plugin-vue": "^6.0.1",
     "@vitest/coverage-v8": "^4.0.18",
     "@vitest/ui": "^4.0.18",
-    "@vue/test-utils": "^2.4.10",
     "@vue/tsconfig": "^0.9.0",
-    "jsdom": "^29.1.1",
-    "typescript": "~6.0.0",
+    "typescript": "~5.8.3",
     "vite": "^8.0.0",
-    "vitest": "^4.0.18",
     "vue-tsc": "^3.0.5"
   }
 }

src/components/AddAccountDialog.vue

@@ -4,7 +4,7 @@ import { useIntegrationStore } from '@KTXC/stores/integrationStore'
 import { useServicesStore } from '@MailManager/stores/servicesStore'
 import { useProvidersStore } from '@MailManager/stores/providersStore'
 import { ServiceObject, type ProviderObject } from '@MailManager/models'
-import type { ProviderDiscoveryStatus, ServiceAddressInterface, ServiceInterface, ServiceLocation } from '@MailManager/types'
+import type { ProviderDiscoveryStatus, ServiceInterface, ServiceLocation } from '@MailManager/types'
 import DiscoveryEntryPanel from '@MailManager/components/steps/DiscoveryEntryPanel.vue'
 import DiscoveryStatusPanel from '@MailManager/components/steps/DiscoveryStatusPanel.vue'
 import ProviderSelectionPanel from '@MailManager/components/steps/ProviderSelectionPanel.vue'
@@ -32,7 +32,6 @@ const MANUAL_STEPS = {
 
 const props = defineProps<{
   modelValue: boolean
-  user?: string
 }>()
 
 const emit = defineEmits<{
@@ -58,11 +57,6 @@ const discoverAddress = ref<string>('')
 const discoverSecret = ref<string | null>(null)
 const discoverHostname = ref<string | null>(null)
 
-// Address entered during discovery, as a service address object
-const discoverServiceAddress = computed<ServiceAddressInterface | null>(() =>
-  discoverAddress.value ? { address: discoverAddress.value } : null
-)
-
 // Step 2: Discovery Status / Provider Selection
 const selectedProvider = shallowRef<ProviderObject | null>(null)
 const selectedService = shallowRef<ServiceObject | null>(null)
@@ -160,7 +154,7 @@ function createServiceObject(
     identifier: null,
     label: data.label ?? null,
     enabled: data.enabled ?? true,
-    primaryAddress: data.primaryAddress ?? discoverServiceAddress.value,
+    primaryAddress: data.primaryAddress ?? (discoverAddress.value || null),
     secondaryAddresses: data.secondaryAddresses ?? null,
     location: data.location ?? null,
     identity: data.identity ?? null,
@@ -243,8 +237,7 @@ async function handleDiscover() {
         discoverSecret.value || undefined,
         discoverHostname.value || undefined,
         identifier,
-        (service) => { discoveredService = service },
-        props.user
+        (service) => { discoveredService = service }
       )
       
       // Success - check if we got results for this provider
@@ -307,7 +300,7 @@ async function handleProviderSelect(identifier: string) {
     ...discoveredJson,
     label: discoveredJson.label || discoverAddress.value,
     enabled: discoveredJson.enabled ?? true,
-    primaryAddress: discoveredJson.primaryAddress ?? discoverServiceAddress.value,
+    primaryAddress: discoveredJson.primaryAddress || discoverAddress.value,
     location: discoveredJson.location
   })
   setSelectedProviderAndService(identifier, service)
@@ -324,7 +317,7 @@ function handleProviderAdvanced(identifier: string) {
     ...discoveredJson,
     label: discoveredJson?.label || discoverAddress.value,
     enabled: discoveredJson?.enabled ?? true,
-    primaryAddress: discoveredJson?.primaryAddress ?? discoverServiceAddress.value,
+    primaryAddress: discoveredJson?.primaryAddress || discoverAddress.value,
     location: discoveredJson?.location ?? null
   })
 
@@ -348,7 +341,7 @@ function handleProviderManualSelect(identifier: string) {
   const service = createServiceObject(identifier, {
     label: discoverAddress.value,
     enabled: true,
-    primaryAddress: discoverServiceAddress.value,
+    primaryAddress: discoverAddress.value,
     location: null,
     identity: null
   })
@@ -386,8 +379,7 @@ async function testConnection() {
     selectedProvider.value.identifier,
     null,
     selectedService.value.location,
-    selectedService.value.identity,
-    props.user
+    selectedService.value.identity
   )
 
   return testResult
@@ -404,7 +396,7 @@ async function saveAccount() {
   try {
     const accountData = {
       label: serviceData.label || discoverAddress.value,
-      primaryAddress: serviceData.primaryAddress ?? discoverServiceAddress.value,
+      primaryAddress: serviceData.primaryAddress || discoverAddress.value,
       enabled: serviceData.enabled,
       location: serviceData.location,
       identity: serviceData.identity,
@@ -413,8 +405,7 @@ async function saveAccount() {
 
     await servicesStore.create(
       selectedProvider.value.identifier,
-      accountData,
-      props.user
+      accountData
     )
 
     emit('saved')

src/components/EditAccountDialog.vue

@@ -14,7 +14,6 @@ const props = defineProps<{
   modelValue: boolean
   serviceProvider: string
   serviceIdentifier: string | number
-  user?: string
 }>()
 
 const emit = defineEmits<{
@@ -104,10 +103,7 @@ async function load() {
   try {
     const [provider, service] = await Promise.all([
       providersStore.provider(props.serviceProvider) ?? providersStore.fetch(props.serviceProvider),
-      // acting-user context always fetches fresh, bypassing the shared cache
-      props.user
-        ? servicesStore.fetch(props.serviceProvider, props.serviceIdentifier, props.user)
-        : servicesStore.service(props.serviceProvider, props.serviceIdentifier) ?? servicesStore.fetch(props.serviceProvider, props.serviceIdentifier)
+      servicesStore.service(props.serviceProvider, props.serviceIdentifier) ?? servicesStore.fetch(props.serviceProvider, props.serviceIdentifier)
     ])
 
     localProvider.value = provider.clone()
@@ -165,16 +161,12 @@ async function testConnection() {
         localService.value.provider,
         null,
         localService.value.location,
-        localService.value.identity,
-        props.user
+        localService.value.identity
       )
     } else {
       testResult = await servicesStore.test(
         localService.value.provider,
-        localService.value.identifier,
-        undefined,
-        undefined,
-        props.user
+        localService.value.identifier
       )
     }
 
@@ -190,10 +182,6 @@ async function testConnection() {
 }
 
 async function saveAccount() {
-  if (!localService.value) {
-    console.error('[Mail Manager][Edit Account Dialog] - No service data to save')
-    return
-  }
   // No changes made, just close the dialog
   if (!localService.value.mutated() && !localService.value.location?.mutated() && !localService.value.identity?.mutated()) {
     close()
@@ -207,8 +195,7 @@ async function saveAccount() {
       localService.value.provider,
       localService.value.identifier as string | number,
       true, // delta update
-      localService.value,
-      props.user
+      localService.value
     )
 
     emit('saved')

src/components/steps/TestAndSavePanel.vue

@@ -134,7 +134,7 @@ watch(
               <v-icon>mdi-label</v-icon>
             </template>
             <v-list-item-title>Account Name</v-list-item-title>
-            <v-list-item-subtitle>{{ localService.label || localService.primaryAddress?.address || 'New Account' }}</v-list-item-subtitle>
+            <v-list-item-subtitle>{{ localService.label || localService.primaryAddress || 'New Account' }}</v-list-item-subtitle>
           </v-list-item>
 
           <!-- Email Address -->
@@ -143,7 +143,7 @@ watch(
               <v-icon>mdi-email</v-icon>
             </template>
             <v-list-item-title>Email Address</v-list-item-title>
-            <v-list-item-subtitle>{{ localService.primaryAddress?.address }}</v-list-item-subtitle>
+            <v-list-item-subtitle>{{ localService.primaryAddress }}</v-list-item-subtitle>
           </v-list-item>
 
           <!-- Provider -->

src/composables/useMailSync.ts

@@ -8,10 +8,12 @@ import { ref, onMounted, onUnmounted } from 'vue';
 import type { Ref } from 'vue';
 import { useEntitiesStore } from '../stores/entitiesStore';
 import { useCollectionsStore } from '../stores/collectionsStore';
-import type { CollectionIdentifier, EntityIdentifier } from '../types/common';
 
-/** A sync source is a collection identifier (provider:service:collection) to monitor */
-export type SyncSource = CollectionIdentifier;
+export interface SyncSource {
+  provider: string;
+  service: string | number;
+  collections: (string | number)[];
+}
 
 interface SyncOptions {
   /** Polling interval in milliseconds (default: 30000 = 30 seconds) */
@@ -26,9 +28,9 @@ export interface MailSyncController {
   isRunning: Ref<boolean>;
   lastSync: Ref<Date | null>;
   error: Ref<string | null>;
-  sources: Ref<CollectionIdentifier[]>;
-  addSource: (source: CollectionIdentifier) => void;
-  removeSource: (source: CollectionIdentifier) => void;
+  sources: Ref<SyncSource[]>;
+  addSource: (source: SyncSource) => void;
+  removeSource: (source: SyncSource) => void;
   clearSources: () => void;
   sync: () => Promise<void>;
   start: () => void;
@@ -49,17 +51,22 @@ export function useMailSync(options: SyncOptions = {}): MailSyncController {
   const isRunning = ref(false);
   const lastSync = ref<Date | null>(null);
   const error = ref<string | null>(null);
-  const sources = ref<CollectionIdentifier[]>([]);
-  // Last known signature per collection identifier (updated by delta)
-  const signatures = ref<Record<string, string>>({});
+  const sources = ref<SyncSource[]>([]);
+  const signatures = ref<Record<string, Record<string, Record<string, string>>>>({});
   
   let syncInterval: ReturnType<typeof setInterval> | null = null;
 
   /**
    * Add a source to sync (mailbox to monitor)
    */
-  function addSource(source: CollectionIdentifier) {
-    if (!sources.value.includes(source)) {
+  function addSource(source: SyncSource) {
+    const exists = sources.value.some(
+      s => s.provider === source.provider 
+        && s.service === source.service 
+        && JSON.stringify(s.collections) === JSON.stringify(source.collections)
+    );
+    
+    if (!exists) {
       sources.value.push(source);
     }
   }
@@ -67,8 +74,13 @@ export function useMailSync(options: SyncOptions = {}): MailSyncController {
   /**
    * Remove a source from sync
    */
-  function removeSource(source: CollectionIdentifier) {
-    const index = sources.value.indexOf(source);
+  function removeSource(source: SyncSource) {
+    const index = sources.value.findIndex(
+      s => s.provider === source.provider 
+        && s.service === source.service 
+        && JSON.stringify(s.collections) === JSON.stringify(source.collections)
+    );
+    
     if (index !== -1) {
       sources.value.splice(index, 1);
     }
@@ -92,69 +104,86 @@ export function useMailSync(options: SyncOptions = {}): MailSyncController {
     try {
       error.value = null;
 
-      // Build flat identifier list for the delta request, embedding the last known
-      // signature for each collection as the entity slot (provider:service:collection:signature)
-      const requestSignatures: Record<string, string> = {};
-      const targets: (CollectionIdentifier | EntityIdentifier)[] = [];
+      // Build sources structure for delta request
+      const deltaSources: any = {};
       
-      sources.value.forEach(collectionId => {
-        // Look up signature from local tracking (updated by delta), falling back to the
-        // collection's own signature if it has not been synced yet
-        let signature = signatures.value[collectionId];
-        if (!signature) {
-          const collectionData = collectionsStore.collection(collectionId);
-          signature = collectionData?.signature || '';
+      sources.value.forEach(source => {
+        if (!deltaSources[source.provider]) {
+          deltaSources[source.provider] = {};
+        }
+        if (!deltaSources[source.provider][source.service]) {
+          deltaSources[source.provider][source.service] = {};
         }
         
-        requestSignatures[collectionId] = signature;
-        targets.push(signature ? `${collectionId}:${signature}` as EntityIdentifier : collectionId);
+        // Add collections to check with their signatures
+        source.collections.forEach(collection => {
+          // Look up signature from local tracking (updated by delta)
+          let signature = signatures.value[source.provider]?.[String(source.service)]?.[String(collection)];
+          
+          // Fallback to collection signature if not yet synced
+          if (!signature) {
+            const collectionData = collectionsStore.collection(source.provider, source.service, collection);
+            signature = collectionData?.signature || '';
+          }
+
+          console.log(`[Sync] Collection ${source.provider}/${source.service}/${collection} signature: "${signature}"`);
+          
+          // Map collection identifier to signature string
+          deltaSources[source.provider][source.service][collection] = signature || '';
+        });
       });
 
       // Get delta changes
-      const deltaResponse = await entitiesStore.delta(targets);
-
+      const deltaResponse = await entitiesStore.delta(deltaSources);
       // If fetchDetails is enabled, fetch full entity data for additions and modifications
       if (fetchDetails) {
         const fetchPromises: Promise<any>[] = [];
         
         Object.entries(deltaResponse).forEach(([provider, providerData]: [string, any]) => {
-          if (providerData === false) {
-            return;
-          }
           Object.entries(providerData).forEach(([service, serviceData]: [string, any]) => {
-            if (serviceData === false) {
-              return;
-            }
             Object.entries(serviceData).forEach(([collection, collectionData]: [string, any]) => {
-              // Skip if no changes (server returns false or a bare signature string)
+              // Skip if no changes (server returns false or string signature)
               if (collectionData === false || typeof collectionData === 'string') {
                 return;
               }
               
-              const collectionId = `${provider}:${service}:${collection}` as CollectionIdentifier;
-
               // Update signature tracking
               if (collectionData.signature) {
-                signatures.value[collectionId] = collectionData.signature;
+                if (!signatures.value[provider]) {
+                  signatures.value[provider] = {};
+                }
+                if (!signatures.value[provider][service]) {
+                  signatures.value[provider][service] = {};
+                }
+                signatures.value[provider][service][collection] = collectionData.signature;
+                console.log(`[Sync] Updated signature for ${provider}/${service}/${collection}: "${collectionData.signature}"`);
               }
               
-              // Skip fetching when the signature did not actually change
-              const oldSignature = requestSignatures[collectionId];
+              // Check if signature actually changed (if not, skip fetching)
+              const oldSignature = deltaSources[provider]?.[service]?.[collection];
               const newSignature = collectionData.signature;
+              
               if (oldSignature && newSignature && oldSignature === newSignature) {
+                // Signature unchanged - server bug returning additions anyway, skip fetch
+                console.log(`[Sync] Skipping fetch for ${provider}/${service}/${collection} - signature unchanged (${newSignature})`);
                 return;
               }
               
-              const changedIds = [
+              const identifiersToFetch = [
                 ...(collectionData.additions || []),
                 ...(collectionData.modifications || []),
               ];
               
-              if (changedIds.length > 0) {
-                const entityTargets = changedIds.map(
-                  (id: string | number) => `${collectionId}:${id}` as EntityIdentifier
+              if (identifiersToFetch.length > 0) {
+                console.log(`[Sync] Fetching ${identifiersToFetch.length} entities for ${provider}/${service}/${collection}`);
+                fetchPromises.push(
+                  entitiesStore.fetch(
+                    provider,
+                    service,
+                    collection,
+                    identifiersToFetch
+                  )
                 );
-                fetchPromises.push(entitiesStore.fetch(entityTargets));
               }
             });
           });

src/models/address.ts

@@ -1,83 +0,0 @@
-/**
- * Address implementation class for Mail Manager services
- *
- * Plain value object (no mutation tracking). ServiceObject getters return
- * fresh instances built from raw data; mutating a getter result does not
- * write back — assign through the setter to persist changes.
- */
-
-import type { ServiceAddressInterface } from '@/types/service';
-
-export class ServiceAddressObject implements ServiceAddressInterface {
-
-    _address: string;
-    _label: string | null;
-
-    constructor(address: string = '', label: string | null = null) {
-        this._address = address;
-        this._label = label;
-    }
-
-    static fromJson(data: ServiceAddressInterface): ServiceAddressObject {
-        return new ServiceAddressObject(data.address, data.label ?? null);
-    }
-
-    toJson(): ServiceAddressInterface {
-        const label = this._label?.trim() ?? '';
-        return {
-            address: this._address.trim(),
-            label: label.length > 0 ? label : null,
-        };
-    }
-
-    toJSON(): ServiceAddressInterface {
-        return this.toJson();
-    }
-
-    clone(): ServiceAddressObject {
-        return new ServiceAddressObject(this._address, this._label);
-    }
-
-    /** Case-insensitive address comparison, ignoring labels */
-    matches(address: string): boolean {
-        return this._address.trim().toLowerCase() === address.trim().toLowerCase();
-    }
-
-    equals(other: ServiceAddressObject | null | undefined): boolean {
-        if (!other) {
-            return false;
-        }
-        const current = this.toJson();
-        const next = other.toJson();
-        return current.address === next.address && (current.label ?? null) === (next.label ?? null);
-    }
-
-    /** Display form: "Label <address>" or bare address */
-    format(): string {
-        const { address, label } = this.toJson();
-        return label ? `${label} <${address}>` : address;
-    }
-
-    get empty(): boolean {
-        return this._address.trim().length === 0;
-    }
-
-    /** Properties (raw values for editing; normalization happens in toJson) */
-
-    get address(): string {
-        return this._address;
-    }
-
-    set address(value: string) {
-        this._address = value;
-    }
-
-    get label(): string | null {
-        return this._label;
-    }
-
-    set label(value: string | null) {
-        this._label = value;
-    }
-
-}

src/models/collection.ts

@@ -2,17 +2,9 @@
  * Class model for Collection Interface
  */
 
-import type {
-    CollectionInterface,
-    CollectionModelInterface,
-    CollectionPropertiesInterface,
-    CollectionPropertiesModelInterface
-} from "@/types/collection";
+import type { CollectionInterface, CollectionModelInterface, CollectionPropertiesInterface, CollectionPropertiesModelInterface } from "@/types/collection";
 import { clonePlain } from './clone-plain';
-import type {
-    CollectionIdentifier,
-    ServiceIdentifier
-} from "@/services";
+import type { CollectionIdentifier, ServiceIdentifier } from "@/services";
 
 export class CollectionObject implements CollectionModelInterface {
 
@@ -24,9 +16,9 @@ export class CollectionObject implements CollectionModelInterface {
             '@type': 'mail:collection',
             version: 1,
             provider: '',
-            service: '' as ServiceIdentifier,
-            collection: null as CollectionIdentifier | null,
-            identifier: '' as CollectionIdentifier,
+            service: '',
+            collection: null,
+            identifier: '',
             properties: {'@type': 'mail:folder', label: ''},
         };
     }

src/models/entity.ts

@@ -19,8 +19,8 @@ export class EntityObject implements EntityModelInterface {
             version: 1,
             provider: '',
             service: '',
-            collection: '' as CollectionIdentifier,
-            identifier: '' as EntityIdentifier,
+            collection: null,
+            identifier: null,
             signature: null,
             created: null,
             modified: null,

src/models/index.ts

@@ -1,6 +1,5 @@
 export { ProviderObject } from './provider';
 export { ServiceObject } from './service';
-export { ServiceAddressObject } from './address';
 export { 
   CollectionObject,
   CollectionPropertiesObject
@@ -8,7 +7,6 @@ export {
 export { EntityObject } from './entity';
 export { 
   MessageObject,
-  MessageAddressObject,
   MessagePartObject
 } from './message';
 export {

src/models/message.ts

@@ -119,19 +119,19 @@ export class MessageObject implements MessageModelInterface {
         return this._data.attachments ? this._data.attachments.map(att => new MessagePartObject(att)) : [];
     }
 
-    get flags(): { seen?: boolean; flagged?: boolean; answered?: boolean; draft?: boolean } | {} {
+    get flags(): { read?: boolean; flagged?: boolean; answered?: boolean; draft?: boolean } | {} {
         return clonePlain(this._data.flags ?? {});
     }
 
     // this should be moved to a mutable object, but for now we can allow it here for convenience
-    set flags(value: { seen?: boolean; flagged?: boolean; answered?: boolean; draft?: boolean }) {
+    set flags(value: { read?: boolean; flagged?: boolean; answered?: boolean; draft?: boolean }) {
         this._data.flags = clonePlain(value);
     }
 
     /** Helper methods */
 
     get isRead(): boolean {
-        return this._data.flags?.seen ?? false;
+        return this._data.flags?.read ?? false;
     }
 
     get isFlagged(): boolean {

src/models/service.ts

@@ -8,7 +8,6 @@ import type {
     ServiceLocation,
     ServiceModelInterface
 } from "@/types/service";
-import { ServiceAddressObject } from './address';
 import { Identity } from './identity';
 import { Location } from './location';
 import { MutationProxy } from './mutation-proxy';
@@ -119,20 +118,20 @@ export class ServiceObject implements ServiceModelInterface {
         return this._data.capabilities ?? {};
     }
 
-    get primaryAddress(): ServiceAddressObject | null {
-        return this._data.primaryAddress ? ServiceAddressObject.fromJson(this._data.primaryAddress) : null;
+    get primaryAddress(): string | null {
+        return this._data.primaryAddress ?? null;
     }
 
-    set primaryAddress(value: ServiceAddressObject | null) {
-        this._data.primaryAddress = value ? value.toJson() : null;
+    set primaryAddress(value: string | null) {
+        this._data.primaryAddress = value;
     }
 
-    get secondaryAddresses(): ServiceAddressObject[] {
-        return (this._data.secondaryAddresses ?? []).map(entry => ServiceAddressObject.fromJson(entry));
+    get secondaryAddresses(): string[] {
+        return this._data.secondaryAddresses ?? [];
     }
 
-    set secondaryAddresses(value: ServiceAddressObject[] | null) {
-        this._data.secondaryAddresses = value ? value.map(entry => entry.toJson()) : null;
+    set secondaryAddresses(value: string[] | null) {
+        this._data.secondaryAddresses = value;
     }
 
     /** Mutable Properties */

src/pages/AccountsPage.vue

@@ -212,7 +212,7 @@ async function handleAccountSaved() {
                     <div>
                       <h3 class="text-h6">{{ service.label }}</h3>
                       <p class="text-caption text-medium-emphasis">
-                        {{ service.primaryAddress?.address || (service.identity?.type === 'BA' ? service.identity.identity : 'No email configured') }}
+                        {{ service.primaryAddress || (service.identity?.type === 'BA' ? service.identity.identity : 'No email configured') }}
                       </p>
                     </div>
                   </div>

src/routes.ts

@@ -2,7 +2,7 @@ const routes = [
   {
     name: 'mail-accounts',
     path: '/accounts',
-    component: () => import('@/pages/Main.vue'),
+    component: () => import('@/pages/AccountsPage.vue'),
     meta: {
       title: 'Mail Accounts',
       requiresAuth: true

src/services/entityService.ts

@@ -2,7 +2,7 @@
  * Entity management service
  */
 
-import { transceivePost, transceiveStream, transceiveDownload, transceiveBlob } from './transceive';
+import { transceivePost, transceiveStream } from './transceive';
 import type {
   EntityFetchRequest,
   EntityFetchResponse,
@@ -27,11 +27,6 @@ import type {
   EntityListBulkRequest,
   EntityPatchResponse,
   EntityPatchRequest,
-  EntityDownloadRequest,
-  EntityPreviewRequest,
-  EntityBlobsRequest,
-  EntityBlobsResponse,
-  EntityBlobsWireResponse,
 } from '../types/entity';
 import { useIntegrationStore } from '@KTXC/stores/integrationStore';
 import { EntityObject } from '../models';
@@ -115,7 +110,7 @@ export const entityService = {
     
     // Convert response to EntityObject instances
     const list: Record<string, EntityObject> = {};
-    Object.entries(response).forEach(([, entity]) => {
+    Object.entries(response).forEach(([identifier, entity]) => {
       list[entity.identifier] = createEntityObject(entity);
     });
     
@@ -221,50 +216,6 @@ export const entityService = {
   async transmit(request: EntityTransmitRequest): Promise<EntityTransmitResponse> {
     return await transceivePost<EntityTransmitRequest, EntityTransmitResponse>('entity.transmit', request);
   },
-
-  /**
-   * Submit a browser-native attachment download request.
-   *
-   * The backend download endpoint is expected to honor the supplied selector
-   * and respond with an attachment payload rather than JSON.
-   */
-  download(request: EntityDownloadRequest): { transaction: string } {
-    return transceiveDownload<EntityDownloadRequest>('entity.download', request);
-  },
-
-  async preview(request: EntityPreviewRequest): Promise<Blob> {
-    return await transceiveBlob<EntityPreviewRequest>('entity.preview', request);
-  },
-
-  /**
-   * Fetch one or more message parts (attachments) inline for rendering.
-   *
-   * Returns JSON with base64-encoded bytes; each result is decoded into a Blob
-   * so callers can create object URLs for preview.
-   */
-  async blobs(request: EntityBlobsRequest): Promise<EntityBlobsResponse> {
-    const wire = await transceivePost<EntityBlobsRequest, EntityBlobsWireResponse>(
-      'entity.blobs',
-      request,
-    );
-    return wire.map((result) => ({
-      source: result.source,
-      part: result.part,
-      mime: result.mime,
-      filename: result.filename,
-      blob: base64ToBlob(result.bytes, result.mime),
-    }));
-  },
 };
 
-/** Decode base64 content into a Blob of the given MIME type. */
-function base64ToBlob(base64: string, mime: string): Blob {
-  const binary = atob(base64);
-  const bytes = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) {
-    bytes[i] = binary.charCodeAt(i);
-  }
-  return new Blob([bytes], { type: mime });
-}
-
 export default entityService;

src/services/index.ts

@@ -8,8 +8,9 @@ export { serviceService } from './serviceService';
 export { collectionService } from './collectionService';
 export { entityService } from './entityService';
 
-export * from '../types/common';
-export * from '../types/provider';
-export * from '../types/service';
-export * from '../types/collection';
-export * from '../types/entity';
+// Type exports
+export type * from '../types/common';
+export type * from '../types/provider';
+export type * from '../types/service';
+export type * from '../types/collection';
+export type * from '../types/entity';

src/services/serviceService.ts

@@ -41,14 +41,14 @@ function createServiceObject(data: ServiceInterface): ServiceObject {
 export const serviceService = {
 
   /**
-   * Retrieve list of services, optionally filtered by provider/service identifiers
+   * Retrieve list of services, optionally filtered by source selector
    * 
    * @param request - list request parameters
    * 
    * @returns Promise with service object list grouped by provider and keyed by service identifier
    */
-  async list(request: ServiceListRequest = {}, user?: string): Promise<Record<string, Record<string, ServiceObject>>> {
-    const response = await transceivePost<ServiceListRequest, ServiceListResponse>('service.list', request, user);
+  async list(request: ServiceListRequest = {}): Promise<Record<string, Record<string, ServiceObject>>> {
+    const response = await transceivePost<ServiceListRequest, ServiceListResponse>('service.list', request);
     
     // Convert nested response to ServiceObject instances
     const providerList: Record<string, Record<string, ServiceObject>> = {};
@@ -70,20 +70,20 @@ export const serviceService = {
    * 
    * @returns Promise with service object
    */
-  async fetch(request: ServiceFetchRequest, user?: string): Promise<ServiceObject> {
-    const response = await transceivePost<ServiceFetchRequest, ServiceFetchResponse>('service.fetch', request, user);
+  async fetch(request: ServiceFetchRequest): Promise<ServiceObject> {
+    const response = await transceivePost<ServiceFetchRequest, ServiceFetchResponse>('service.fetch', request);
     return createServiceObject(response);
   },
 
   /**
-   * Retrieve service availability status for the given service identifiers
+   * Retrieve service availability status for a given source selector
    * 
    * @param request - extant request parameters
    * 
    * @returns Promise with service availability status
    */
-  async extant(request: ServiceExtantRequest, user?: string): Promise<ServiceExtantResponse> {
-    return await transceivePost<ServiceExtantRequest, ServiceExtantResponse>('service.extant', request, user);
+  async extant(request: ServiceExtantRequest): Promise<ServiceExtantResponse> {
+    return await transceivePost<ServiceExtantRequest, ServiceExtantResponse>('service.extant', request);
   },
 
   /**
@@ -96,8 +96,7 @@ export const serviceService = {
    */
   async discover(
     request: ServiceDiscoverRequest,
-    onService: (service: ServiceObject) => void,
-    user?: string
+    onService: (service: ServiceObject) => void
   ): Promise<{ total: number }> {
     return await transceiveStream<ServiceDiscoverRequest, ServiceDiscoverResponse>(
       'service.discover',
@@ -108,12 +107,11 @@ export const serviceService = {
           provider: service.provider,
           identifier: null,
           label: null,
-          enabled: true,
+          enabled: false,
           location: service.location,
         };
         onService(createServiceObject(serviceData));
-      },
-      user
+      }
     );
   },
 
@@ -123,8 +121,8 @@ export const serviceService = {
    * @param request - Service test request
    * @returns Promise with test results
    */
-  async test(request: ServiceTestRequest, user?: string): Promise<ServiceTestResponse> {
-    return await transceivePost<ServiceTestRequest, ServiceTestResponse>('service.test', request, user);
+  async test(request: ServiceTestRequest): Promise<ServiceTestResponse> {
+    return await transceivePost<ServiceTestRequest, ServiceTestResponse>('service.test', request);
   },
 
   /**
@@ -134,8 +132,8 @@ export const serviceService = {
    * 
    * @returns Promise with created service object
    */
-  async create(request: ServiceCreateRequest, user?: string): Promise<ServiceObject> {
-    const response = await transceivePost<ServiceCreateRequest, ServiceCreateResponse>('service.create', request, user);
+  async create(request: ServiceCreateRequest): Promise<ServiceObject> {
+    const response = await transceivePost<ServiceCreateRequest, ServiceCreateResponse>('service.create', request);
     return createServiceObject(response);
   },
 
@@ -146,8 +144,8 @@ export const serviceService = {
    * 
    * @returns Promise with updated service object
    */
-  async update(request: ServiceUpdateRequest, user?: string): Promise<ServiceObject> {
-    const response = await transceivePost<ServiceUpdateRequest, ServiceUpdateResponse>('service.update', request, user);
+  async update(request: ServiceUpdateRequest): Promise<ServiceObject> {
+    const response = await transceivePost<ServiceUpdateRequest, ServiceUpdateResponse>('service.update', request);
     return createServiceObject(response);
   },
 
@@ -158,8 +156,8 @@ export const serviceService = {
    * 
    * @returns Promise with deletion result
    */
-  async delete(request: { provider: string; identifier: string | number }, user?: string): Promise<any> {
-    return await transceivePost<ServiceDeleteRequest, ServiceDeleteResponse>('service.delete', request, user);
+  async delete(request: { provider: string; identifier: string | number }): Promise<any> {
+    return await transceivePost<ServiceDeleteRequest, ServiceDeleteResponse>('service.delete', request);
   },
 };
 

src/services/transceive.ts

@@ -141,106 +141,3 @@ export async function transceiveStream<TRequest, TData>(
 
   return { total };
 }
-
-/**
- * Submit a browser-native file download request via a top-level form POST.
- *
- * This avoids buffering the response body in application-managed JavaScript
- * memory. The backend is expected to accept form fields where `data` contains
- * the serialized operation payload and to return an attachment response.
- */
-export function transceiveDownload<TRequest>(
-  operation: string,
-  data: TRequest,
-  user?: string,
-): { transaction: string } {
-  if (typeof document === 'undefined' || typeof window === 'undefined') {
-    throw new Error('Browser window is not available for download submission');
-  }
-
-  const request: ApiRequest<TRequest> = {
-    version: API_VERSION,
-    transaction: generateTransactionId(),
-    operation,
-    data,
-    user,
-  };
-
-  const form = document.createElement('form');
-  form.method = 'POST';
-  form.action = API_URL;
-  form.target = '_blank';
-  form.style.display = 'none';
-
-  appendHiddenField(form, 'version', String(request.version));
-  appendHiddenField(form, 'transaction', request.transaction);
-  appendHiddenField(form, 'operation', request.operation);
-  appendFormValue(form, 'data', request.data);
-
-  if (request.user) {
-    appendHiddenField(form, 'user', request.user);
-  }
-
-  document.body.appendChild(form);
-  form.submit();
-  form.remove();
-
-  return { transaction: request.transaction };
-}
-
-export async function transceiveBlob<TRequest>(operation: string, data: TRequest): Promise<Blob> {
-  const request: ApiRequest<TRequest> = {
-    version: API_VERSION,
-    transaction: generateTransactionId(),
-    operation,
-    data,
-  };
-  let blob: Blob | null = null;
-  await fetchWrapper.post(API_URL, request, {
-    headers: { 'Accept': '*/*' },
-    onStream: async (response: Response) => {
-      if (response.status === 204) {
-        throw new Error(`[${operation}] Preview unavailable`);
-      }
-      blob = await response.blob();
-    },
-  });
-  if (blob === null) throw new Error(`[${operation}] Empty preview response`);
-  return blob;
-}
-
-
-function appendHiddenField(form: HTMLFormElement, name: string, value: string): void {
-  const input = document.createElement('input');
-  input.type = 'hidden';
-  input.name = name;
-  input.value = value;
-  form.appendChild(input);
-}
-
-function appendFormValue(form: HTMLFormElement, name: string, value: unknown): void {
-  if (value === undefined) {
-    return;
-  }
-
-  if (value === null) {
-    appendHiddenField(form, name, '');
-    return;
-  }
-
-  if (Array.isArray(value)) {
-    value.forEach((item, index) => {
-      appendFormValue(form, `${name}[${index}]`, item);
-    });
-    return;
-  }
-
-  if (typeof value === 'object') {
-    Object.entries(value as Record<string, unknown>).forEach(([key, nestedValue]) => {
-      appendFormValue(form, `${name}[${key}]`, nestedValue);
-    });
-    return;
-  }
-
-  appendHiddenField(form, name, String(value));
-}

src/stores/entitiesStore.ts

@@ -7,10 +7,7 @@ import { defineStore } from 'pinia'
 import { entityService } from '../services'
 import { EntityObject, MessageObject } from '../models'
 import type {
-  EntityBlobSelector,
-  EntityBlobsResponse,
-  EntityDownloadRequest,
-  EntityPreviewRequest,
+  EntityListStreamRequest,
   EntityTransmitRequest,
   EntityTransmitResponse,
 } from '../types/entity'
@@ -21,7 +18,7 @@ import type {
   ListRange,
   ListSort,
 } from '../types/common'
-import type { MessageInterface, MessagePartInterface } from '@/types/message'
+import type { MessageInterface } from '@/types/message'
 
 export const useEntitiesStore = defineStore('mailEntitiesStore', () => {
   // State
@@ -46,7 +43,10 @@ export const useEntitiesStore = defineStore('mailEntitiesStore', () => {
   /**
    * Get a specific entity from store, with optional retrieval
    * 
-   * @param target - entity identifier
+   * @param provider - provider identifier
+   * @param service - service identifier
+   * @param collection - collection identifier
+   * @param identifier - entity identifier
    * @param retrieve - Retrieve behavior: true = fetch if missing or refresh, false = cache only
    * 
    * @returns Entity object or null
@@ -63,7 +63,9 @@ export const useEntitiesStore = defineStore('mailEntitiesStore', () => {
   /**
    * Get all entities for a specific collection
    * 
-   * @param target - collection identifier
+   * @param provider - provider identifier
+   * @param service - service identifier
+   * @param collection - collection identifier
    * @param retrieve - Retrieve behavior: true = fetch if missing or refresh, false = cache only
    * 
    * @returns Array of entity objects
@@ -113,10 +115,13 @@ export const useEntitiesStore = defineStore('mailEntitiesStore', () => {
     }
   }
   
-    /**
-   * Retrieve specific entities by their identifiers
+  /**
+   * Retrieve specific entities by provider, service, collection, and identifiers
    * 
-   * @param targets - array of entity identifiers to fetch
+   * @param provider - provider identifier
+   * @param service - service identifier
+   * @param collection - collection identifier
+   * @param identifiers - array of entity identifiers to fetch
    * 
    * @returns Promise with entity objects keyed by identifier
    */
@@ -166,30 +171,28 @@ export const useEntitiesStore = defineStore('mailEntitiesStore', () => {
   /**
    * Retrieve delta changes for entities
    * 
-   * @param targets - collection identifiers (provider:service:collection), optionally
-   *                  suffixed with a known signature (provider:service:collection:signature)
-   *                  to request a delta relative to that signature
+   * @param sources - source selector for delta check
    * 
    * @returns Promise with delta changes (additions, modifications, deletions)
    * 
    * Note: Delta returns only identifiers, not full entities.
    * Caller should fetch full entities for additions/modifications separately.
    */
-  async function delta(targets: (CollectionIdentifier | EntityIdentifier)[]) {
+  async function delta(sources: CollectionIdentifier[]) {
     transceiving.value = true
     try {
-      const response = await entityService.delta({ targets })
+      const response = await entityService.delta({ sources })
       
       // Process delta and update store
-      Object.entries(response).forEach(([, providerData]) => {
+      Object.entries(response).forEach(([provider, providerData]) => {
         // Skip if no changes for provider
         if (providerData === false) return
         
-        Object.entries(providerData).forEach(([, serviceData]) => {
+        Object.entries(providerData).forEach(([service, serviceData]) => {
           // Skip if no changes for service
           if (serviceData === false) return
           
-          Object.entries(serviceData).forEach(([, collectionData]) => {
+          Object.entries(serviceData).forEach(([collection, collectionData]) => {
             // Skip if no changes for collection
             if (collectionData === false) return
             
@@ -471,58 +474,6 @@ export const useEntitiesStore = defineStore('mailEntitiesStore', () => {
     }
   }
 
-  async function download(target: EntityIdentifier, part?: Partial<MessagePartInterface>) {
-    let targetPart: EntityBlobSelector | undefined = undefined
-    if (part && (part.blobId || part.partId || part.cid)) {
-      targetPart = {
-        blobId: part.blobId ?? undefined,
-        partId: part.partId ?? undefined,
-        cid: part.cid ?? undefined,
-      }
-    }
-
-    let filename: string
-    if (part && part.name && part.name.trim().length > 0) {
-      filename = part.name.trim()
-    } else if (part) {
-      filename = `attachment-${part.partId || part.blobId || part.cid || 'unknown'}`
-    } else {
-      filename = 'message.eml'
-    }
-
-    const request: EntityDownloadRequest = {
-      target,
-      part: targetPart,
-      filename,
-    }
-
-    try {
-      entityService.download(request)
-    } catch (error: any) {
-      console.error('[Mail Manager][Store] - Failed to submit attachment download:', error)
-      throw error
-    }
-  }
-
-  /**
-   * Fetch one or more message parts (attachments) inline as Blobs, for preview.
-   */
-  async function blobs(
-    target: EntityIdentifier,
-    parts: EntityBlobSelector[],
-  ): Promise<EntityBlobsResponse> {
-    try {
-      return await entityService.blobs({ target, parts })
-    } catch (error: any) {
-      console.error('[Mail Manager][Store] - Failed to fetch attachment blobs:', error)
-      throw error
-    }
-  }
-
-  async function preview(request: EntityPreviewRequest): Promise<Blob> {
-    return await entityService.preview(request)
-  }
-
   // Return public API
   return {
     // State (readonly)
@@ -544,8 +495,5 @@ export const useEntitiesStore = defineStore('mailEntitiesStore', () => {
     delta,
     move,
     transmit,
-    download,
-    preview,
-    blobs,
   }
 })

src/stores/providersStore.ts

@@ -6,7 +6,7 @@ import { ref, computed, readonly } from 'vue'
 import { defineStore } from 'pinia'
 import { providerService } from '../services'
 import { ProviderObject } from '../models/provider'
-import type { ProviderIdentifier } from '../types'
+import type { SourceSelector } from '../types'
 
 export const useProvidersStore = defineStore('mailProvidersStore', () => {
   // State
@@ -50,14 +50,14 @@ export const useProvidersStore = defineStore('mailProvidersStore', () => {
   /**
    * Retrieve all or specific providers, optionally filtered by source selector
    * 
-   * @param targets - list request parameters
+   * @param request - list request parameters
    * 
    * @returns Promise with provider object list keyed by provider identifier
    */
-  async function list(targets?: ProviderIdentifier[]): Promise<Record<string, ProviderObject>> {
+  async function list(sources?: SourceSelector): Promise<Record<string, ProviderObject>> {
     transceiving.value = true
     try {
-      const providers = await providerService.list({ targets })
+      const providers = await providerService.list({ sources })
 
       // Merge retrieved providers into state
       _providers.value = { ..._providers.value, ...providers }
@@ -75,14 +75,14 @@ export const useProvidersStore = defineStore('mailProvidersStore', () => {
   /**
    * Retrieve a specific provider by identifier
    * 
-   * @param target - fetch target identifier
+   * @param identifier - provider identifier
    * 
    * @returns Promise with provider object
    */
-  async function fetch(target: string): Promise<ProviderObject> {
+  async function fetch(identifier: string): Promise<ProviderObject> {
     transceiving.value = true
     try {
-      const provider = await providerService.fetch({ target })
+      const provider = await providerService.fetch({ identifier })
 
       // Merge fetched provider into state
       _providers.value[provider.identifier] = provider
@@ -100,14 +100,14 @@ export const useProvidersStore = defineStore('mailProvidersStore', () => {
   /**
    * Retrieve provider availability status for a given source selector
    * 
-   * @param targets - list of provider identifiers to check availability for
+   * @param sources - source selector to check availability for
    * 
    * @returns Promise with provider availability status
    */
-  async function extant(targets: ProviderIdentifier[]) {
+  async function extant(sources: SourceSelector) {
     transceiving.value = true
     try {
-      const response = await providerService.extant({ targets })
+      const response = await providerService.extant({ sources })
 
       Object.entries(response).forEach(([providerId, providerStatus]) => {
         if (providerStatus === false) {
@@ -115,7 +115,7 @@ export const useProvidersStore = defineStore('mailProvidersStore', () => {
         }
       })
 
-      console.debug('[Mail Manager][Store] - Successfully checked', targets ? targets.length : 0, 'providers')
+      console.debug('[Mail Manager][Store] - Successfully checked', sources ? Object.keys(sources).length : 0, 'providers')
       return response
     } catch (error: any) {
       console.error('[Mail Manager][Store] - Failed to check providers:', error)

src/stores/servicesStore.ts

@@ -7,9 +7,9 @@ import { defineStore } from 'pinia'
 import { serviceService } from '../services'
 import { ServiceObject } from '../models/service'
 import type {
-  CollectionIdentifier,
   ServiceIdentifier,
   ServiceLocation,
+  SourceSelector,
   ServiceIdentity,
   ServiceInterface,
 } from '../types'
@@ -101,10 +101,7 @@ export const useServicesStore = defineStore('mailServicesStore', () => {
    * @returns Service object or null
    */
   function serviceForAddress(address: string, retrieve: boolean = false): ServiceObject | null {
-    const service = Object.values(_services.value).find(s =>
-      s.primaryAddress?.matches(address) ||
-      s.secondaryAddresses.some(candidate => candidate.matches(address)),
-    )
+    const service = Object.values(_services.value).find(s => s.primaryAddress === address || s.secondaryAddresses?.includes(address))
     
     if (retrieve === true && !service) {
       console.debug(`[Mail Manager][Store] - No service found for address "${address}", discovery may be needed`)
@@ -125,16 +122,16 @@ export const useServicesStore = defineStore('mailServicesStore', () => {
   // Actions
   
   /**
-   * Retrieve all or specific services, optionally filtered by provider/service identifiers
+   * Retrieve all or specific services, optionally filtered by source selector
    * 
-   * @param targets - optional array of provider:service (or provider:service:collection) identifiers
+   * @param sources - optional source selector
    * 
    * @returns Promise with service object list keyed by provider and service identifier
    */
-  async function list(targets?: ServiceIdentifier[] | CollectionIdentifier[], user?: string): Promise<Record<string, ServiceObject>> {
+  async function list(sources?: SourceSelector): Promise<Record<string, ServiceObject>> {
     transceiving.value = true
     try {
-      const response = await serviceService.list({ targets }, user)
+      const response = await serviceService.list({ sources })
 
       // Flatten nested structure: provider-id: { service-id: object } -> "provider-id:service-id": object
       const services: Record<string, ServiceObject> = {}
@@ -145,10 +142,8 @@ export const useServicesStore = defineStore('mailServicesStore', () => {
         })
       })
 
-      // Merge retrieved services into state (acting-user context stays out of the shared cache)
-      if (!user) {
-        _services.value = { ..._services.value, ...services }
-      }
+      // Merge retrieved services into state
+      _services.value = { ..._services.value, ...services }
 
       console.debug('[Mail Manager][Store] - Successfully retrieved', Object.keys(services).length, 'services')
       return services
@@ -168,16 +163,14 @@ export const useServicesStore = defineStore('mailServicesStore', () => {
    * 
    * @returns Promise with service object
    */
-  async function fetch(provider: string, identifier: string | number, user?: string): Promise<ServiceObject> {
+  async function fetch(provider: string, identifier: string | number): Promise<ServiceObject> {
     transceiving.value = true
     try {
-      const service = await serviceService.fetch({ provider, identifier }, user)
+      const service = await serviceService.fetch({ provider, identifier })
       
-      // Merge fetched service into state (acting-user context stays out of the shared cache)
+      // Merge fetched service into state
       const key = identifierKey(service.provider, service.identifier)
-      if (!user) {
-        _services.value[key] = service
-      }
+      _services.value[key] = service
 
       console.debug('[Mail Manager][Store] - Successfully fetched service:', key)
       return service
@@ -190,18 +183,18 @@ export const useServicesStore = defineStore('mailServicesStore', () => {
   }
 
   /**
-   * Retrieve service availability status for the given service identifiers
+   * Retrieve service availability status for a given source selector
    * 
-   * @param targets - array of provider:service identifiers to check availability for
+   * @param sources - source selector to check availability for
    * 
    * @returns Promise with service availability status
    */
-  async function extant(targets: ServiceIdentifier[], user?: string) {
+  async function extant(sources: SourceSelector) {
     transceiving.value = true
     try {
-      const response = await serviceService.extant({ targets }, user)
+      const response = await serviceService.extant({ sources })
       
-      console.debug('[Mail Manager][Store] - Successfully checked', targets?.length ?? 0, 'services')
+      console.debug('[Mail Manager][Store] - Successfully checked', sources ? Object.keys(sources).length : 0, 'services')
       return response
     } catch (error: any) {
       console.error('[Mail Manager][Store] - Failed to check services:', error)
@@ -219,16 +212,14 @@ export const useServicesStore = defineStore('mailServicesStore', () => {
    * 
    * @returns Promise with created service object
    */
-  async function create(provider: string, data: Partial<ServiceInterface>, user?: string): Promise<ServiceObject> {
+  async function create(provider: string, data: Partial<ServiceInterface>): Promise<ServiceObject> {
     transceiving.value = true
     try {
-      const service = await serviceService.create({ provider, data }, user)
+      const service = await serviceService.create({ provider, data })
       
-      // Merge created service into state (acting-user context stays out of the shared cache)
+      // Merge created service into state
       const key = identifierKey(service.provider, service.identifier)
-      if (!user) {
-        _services.value[key] = service
-      }
+      _services.value[key] = service
       
       console.debug('[Mail Manager][Store] - Successfully created service:', key)
       return service
@@ -250,7 +241,7 @@ export const useServicesStore = defineStore('mailServicesStore', () => {
    * 
    * @returns Promise with updated service object
    */
-  async function update(provider: string, identifier: string | number, delta: boolean, data: ServiceObject | Partial<ServiceInterface>, user?: string): Promise<ServiceObject> {
+  async function update(provider: string, identifier: string | number, delta: boolean, data: ServiceObject | Partial<ServiceInterface>): Promise<ServiceObject> {
     transceiving.value = true
     try {
       // convert ServiceObject to JSON if needed
@@ -261,13 +252,11 @@ export const useServicesStore = defineStore('mailServicesStore', () => {
         payload = data
       }
 
-      const service = await serviceService.update({ provider, identifier, delta, data: payload }, user)
+      const service = await serviceService.update({ provider, identifier, delta, data: payload })
       
-      // Merge updated service into state (acting-user context stays out of the shared cache)
+      // Merge updated service into state
       const key = identifierKey(service.provider, service.identifier)
-      if (!user) {
-        _services.value[key] = service
-      }
+      _services.value[key] = service
       
       console.debug('[Mail Manager][Store] - Successfully updated service:', key)
       return service
@@ -287,16 +276,14 @@ export const useServicesStore = defineStore('mailServicesStore', () => {
    * 
    * @returns Promise with deletion result
    */
-  async function remove(provider: string, identifier: string | number, user?: string): Promise<any> {
+  async function remove(provider: string, identifier: string | number): Promise<any> {
     transceiving.value = true
     try {
-      await serviceService.delete({ provider, identifier }, user)
+      await serviceService.delete({ provider, identifier })
       
       // Remove deleted service from state
       const key = identifierKey(provider, identifier)
-      if (!user) {
-        delete _services.value[key]
-      }
+      delete _services.value[key]
 
       console.debug('[Mail Manager][Store] - Successfully deleted service:', key)
     } catch (error: any) {
@@ -324,7 +311,6 @@ export const useServicesStore = defineStore('mailServicesStore', () => {
     location: string | undefined,
     provider: string | undefined,
     onService?: (service: ServiceObject) => void,
-    user?: string,
   ): Promise<{ total: number }> {
     transceiving.value = true
     
@@ -333,8 +319,7 @@ export const useServicesStore = defineStore('mailServicesStore', () => {
         { identity, secret, location, provider },
         (service: ServiceObject) => {
           onService?.(service)
-        },
-        user
+        }
       )
 
       console.debug('[Mail Manager][Store] - Successfully discovered', result.total, 'services')
@@ -362,7 +347,6 @@ export const useServicesStore = defineStore('mailServicesStore', () => {
     identifier?: string | number | null,
     location?: ServiceLocation | Location | null,
     identity?: ServiceIdentity | Identity | null,
-    user?: string,
   ): Promise<any> {
     transceiving.value = true
     try {
@@ -385,7 +369,7 @@ export const useServicesStore = defineStore('mailServicesStore', () => {
         identity = identity.toJson()
       }
 
-      const response = await serviceService.test({ provider, identifier, location, identity }, user)
+      const response = await serviceService.test({ provider, identifier, location, identity })
       
       console.debug('[Mail Manager][Store] - Successfully tested service:', provider, identifier || location)
       return response

src/types/collection.ts

@@ -1,12 +1,7 @@
 /**
  * Collection type definitions
  */
-import type {
-  ServiceIdentifier,
-  CollectionIdentifier,
-  ListFilter,
-  ListSort
-} from './common';
+import type { CollectionIdentifier, ListFilter, ListSort, ServiceIdentifier, SourceSelector } from './common';
 
 /**
  * Collection information

src/types/common.ts

@@ -85,11 +85,34 @@ export type ApiStreamResponse<T = any> =
   | ApiStreamDataResponse<T>;
 
 /**
- * Identifiers for targeting specific providers, services, collections, or entities in list or extant operations.
+ * Selector for targeting specific providers, services, collections, or entities in list or extant operations.
  * 
- * Operations accept flat arrays of colon-separated identifier strings, e.g.
- * ["imap:account1:INBOX", "imap:account1:Sent:1001"].
+ * Example usage:
+ * {
+ *   "provider1": true, // Select all services/collections/entities under provider1
+ *   "provider2": {
+ *     "serviceA": true, // Select all collections/entities under serviceA of provider2
+ *     "serviceB": {
+ *       "collectionX": true, // Select all entities under collectionX of serviceB of provider2
+ *       "collectionY": [1, 2, 3] // Select entities with identifiers 1, 2, and 3 under collectionY of serviceB of provider2
+ *     }
+ *   }
+ * }
  */
+export type SourceSelector = {
+  [provider: string]: boolean | ServiceSelector;
+};
+
+export type ServiceSelector = {
+  [service: string]: boolean | CollectionSelector;
+};
+
+export type CollectionSelector = {
+  [collection: string | number]: boolean | EntitySelector;
+};
+
+export type EntitySelector = (string | number)[];
+
 export type ProviderIdentifier = `${string}`;
 export type ServiceIdentifier = `${string}:${string}`;
 export type CollectionIdentifier = `${string}:${string}:${string | number}`;

src/types/entity.ts

@@ -8,10 +8,7 @@ import type {
   ListRange,
   ListSort,
 } from './common';
-import type {
-  MessageInterface,
-  MessageModelInterface
-} from './message';
+import type { MessageInterface, MessageModelInterface } from './message';
 
 /**
  * Entity definition
@@ -95,9 +92,7 @@ export interface EntityExtantResponse {
  * Entity delta
  */
 export interface EntityDeltaRequest {
-  // Each target is provider:service:collection, or provider:service:collection:signature
-  // to request a delta relative to a known signature (the signature is the entity slot).
-  targets: (CollectionIdentifier | EntityIdentifier)[];
+  sources: CollectionIdentifier[];
 }
 
 export interface EntityDeltaResponse {
@@ -211,45 +206,3 @@ export interface EntityTransmitResponse {
   id: string;
   status: 'queued' | 'sent';
 }
-
-/**
- * Entity Blob Fetch
- */
-export interface EntityBlobSelector {
-  blobId?: string;
-  partId?: string;
-  cid?: string;
-}
-
-export interface EntityDownloadRequest {
-  target: EntityIdentifier;
-  part?: EntityBlobSelector;
-  filename?: string | null;
-}
-
-export interface EntityPreviewRequest {
-  target: EntityIdentifier;
-  part: EntityBlobSelector & { type: string; size?: number | null };
-  variant?: string;
-}
-
-export interface EntityBlobsRequest {
-  target: EntityIdentifier;
-  parts: EntityBlobSelector[];
-}
-
-export interface EntityBlobsWireResult {
-  source: EntityIdentifier;
-  part: EntityBlobSelector;
-  mime: string;
-  filename: string;
-  bytes: string;
-}
-
-export interface EntityBlobsWireResponse extends Array<EntityBlobsWireResult> {}
-
-export interface EntityBlobsResult extends Omit<EntityBlobsWireResult, 'bytes'> {
-  blob: Blob;
-}
-
-export interface EntityBlobsResponse extends Array<EntityBlobsResult> {}

src/types/message.ts

@@ -35,7 +35,7 @@ export interface MessageAddressInterface {
 }
 
 export interface MessageFlagsInterface {
-  seen?: boolean;
+  read?: boolean;
   flagged?: boolean;
   answered?: boolean;
   draft?: boolean;

src/types/provider.ts

@@ -1,7 +1,7 @@
 /**
  * Provider type definitions
  */
-import type { ProviderIdentifier } from "./common";
+import type { SourceSelector } from "./common";
 
 /**
  * Provider capabilities
@@ -35,18 +35,18 @@ export interface ProviderModelInterface extends Omit<ProviderInterface, '@type'
  * Provider list
  */
 export interface ProviderListRequest {
-  targets?: ProviderIdentifier[];
+  sources?: SourceSelector;
 }
 
 export interface ProviderListResponse {
-  [identifier: ProviderIdentifier]: ProviderInterface;
+  [identifier: string]: ProviderInterface;
 }
 
 /**
  * Provider fetch 
  */
 export interface ProviderFetchRequest {
-  target: ProviderIdentifier;
+  identifier: string;
 }
 
 export interface ProviderFetchResponse extends ProviderInterface {}
@@ -55,9 +55,9 @@ export interface ProviderFetchResponse extends ProviderInterface {}
  * Provider extant 
  */
 export interface ProviderExtantRequest {
-  targets: ProviderIdentifier[];
+  sources: SourceSelector;
 }
 
 export interface ProviderExtantResponse {
-  [identifier: ProviderIdentifier]: boolean;
+  [identifier: string]: boolean;
 }

src/types/service.ts

@@ -1,13 +1,11 @@
 /**
  * Service type definitions
  */
-import type { ServiceAddressObject } from '@/models/address';
 import type { Identity } from '@/models/identity';
 import type { Location } from '@/models/location';
 import type {
-  ServiceIdentifier,
-  CollectionIdentifier,
   ListFilterComparisonOperator,
+  SourceSelector,
 } from './common';
 
 /**
@@ -42,15 +40,6 @@ export interface ServiceCapabilitiesInterface {
   [key: string]: boolean | object | string | string[] | undefined;
 }
 
-/**
- * Service sender address (primary or secondary/alias)
- * Mirrors the shared Mail AddressInterface JSON shape
- */
-export interface ServiceAddressInterface {
-  address: string;
-  label?: string | null;
-}
-
 /**
  * Service information
  */
@@ -64,25 +53,23 @@ export interface ServiceInterface {
   capabilities?: ServiceCapabilitiesInterface;
   location?: ServiceLocation | null;
   identity?: ServiceIdentity | null;
-  primaryAddress?: ServiceAddressInterface | null;
-  secondaryAddresses?: ServiceAddressInterface[] | null;
+  primaryAddress?: string | null;
+  secondaryAddresses?: string[] | null;
   auxiliary?: Record<string, any>;  // Provider-specific extension data
 }
 
 export interface ServiceModelInterface extends Omit<{
     [K in keyof ServiceInterface]-?: Exclude<ServiceInterface[K], undefined>;
-}, '@type' | 'version' | 'location' | 'identity' | 'primaryAddress' | 'secondaryAddresses'> {
+}, '@type' | 'version' | 'location' | 'identity'> {
   location: Location | null;
   identity: Identity | null;
-  primaryAddress: ServiceAddressObject | null;
-  secondaryAddresses: ServiceAddressObject[];
 }
 
 /**
  * Service list
  */
 export interface ServiceListRequest {
-  targets?: ServiceIdentifier[] | CollectionIdentifier[];
+  sources?: SourceSelector;
 }
 
 export interface ServiceListResponse {
@@ -105,7 +92,7 @@ export interface ServiceFetchResponse extends ServiceInterface {}
  * Service extant
  */
 export interface ServiceExtantRequest {
-  targets: ServiceIdentifier[];
+  sources: SourceSelector;
 }
 
 export interface ServiceExtantResponse {

tests/js/unit/base.test.ts

@@ -1,30 +0,0 @@
-import { describe, it, expect } from 'vitest'
-
-describe('Basic Tests', () => {
-  it('should perform basic assertion', () => {
-    expect(true).toBe(true)
-  })
-
-  it('should test array operations', () => {
-    const array = ['foo', 'bar', 'baz']
-
-    expect(array).toHaveLength(3)
-    expect(array).toContain('bar')
-    expect(array[0]).toBe('foo')
-  })
-
-  it('should test string operations', () => {
-    const string = 'Hello, World!'
-
-    expect(string).toContain('World')
-    expect(string.length).toBe(13)
-  })
-
-  it('should test object operations', () => {
-    const obj = { foo: 'bar', count: 42 }
-
-    expect(obj).toHaveProperty('foo')
-    expect(obj.foo).toBe('bar')
-    expect(obj.count).toBeGreaterThan(40)
-  })
-})

tests/js/vitest.config.ts

@@ -1,33 +0,0 @@
-import { fileURLToPath } from 'node:url'
-import { defineConfig, configDefaults } from 'vitest/config'
-import vue from '@vitejs/plugin-vue'
-import path from 'path'
-
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = path.dirname(__filename)
-
-export default defineConfig({
-  plugins: [vue()],
-  resolve: {
-    alias: {
-      '@': path.resolve(__dirname, '../../src'),
-      '@KTXC': path.resolve(__dirname, '../../../../core/src'),
-    },
-  },
-  test: {
-    environment: 'jsdom',
-    exclude: [...configDefaults.exclude, 'e2e/**'],
-    root: fileURLToPath(new URL('../../', import.meta.url)),
-    coverage: {
-      provider: 'v8',
-      reporter: ['text', 'json', 'html'],
-      exclude: [
-        'node_modules/',
-        'tests/',
-        '**/*.d.ts',
-        '**/*.config.*',
-        '**/dist/**',
-      ],
-    },
-  },
-})

tests/php/Integration/BaseTest.php

@@ -1,29 +0,0 @@
-<?php
-
-namespace KTXT\MailManager\Tests\Integration;
-
-use PHPUnit\Framework\TestCase;
-
-class BaseTest extends TestCase
-{
-    public function testBasicAssertion(): void
-    {
-        $this->assertTrue(true);
-    }
-
-    public function testArrayOperations(): void
-    {
-        $array = ['foo' => 'bar'];
-
-        $this->assertArrayHasKey('foo', $array);
-        $this->assertEquals('bar', $array['foo']);
-    }
-
-    public function testStringOperations(): void
-    {
-        $string = 'Hello, World!';
-
-        $this->assertStringContainsString('World', $string);
-        $this->assertEquals(13, strlen($string));
-    }
-}

tests/php/bootstrap.php

@@ -2,16 +2,6 @@
 
 require dirname(__DIR__, 2).'/lib/vendor/autoload.php';
 
-// When this module is checked out inside a full server (server/modules/<handle>,
-// as it is in CI and in this monorepo checkout), also load the server's own
-// core/shared autoloader so tests can reference framework (KTXC/KTXF) types.
-// Standalone module checkouts without a server alongside them skip this.
-define('SERVER_ROOT', dirname(__DIR__, 4));
-$serverAutoload = SERVER_ROOT . '/vendor/autoload.php';
-if (is_file($serverAutoload)) {
-    require $serverAutoload;
-}
-
 if (isset($_SERVER['APP_DEBUG']) && $_SERVER['APP_DEBUG']) {
     umask(0000);
 }

tests/php/phpunit.unit.xml

@@ -21,9 +21,6 @@
         <testsuite name="Unit Tests">
             <directory>unit</directory>
         </testsuite>
-        <testsuite name="Integration Tests">
-            <directory>Integration</directory>
-        </testsuite>
     </testsuites>
 
     <source ignoreSuppressionOfDeprecations="true"
@@ -32,7 +29,8 @@
             restrictWarnings="true"
     >
         <include>
-            <directory>../../lib</directory>
+            <directory>../../core/lib</directory>
+            <directory>../../shared/lib</directory>
         </include>
     </source>