refactor: documents interfaces

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

shared/lib/Documents/Collection/CollectionBaseAbstract.php

@@ -7,12 +7,13 @@ declare(strict_types=1);
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-namespace KTXF\Resource\Documents\Collection;
+namespace KTXF\Documents\Collection;
 
+use KTXF\Resource\Identifier\CollectionIdentifier;
 use KTXF\Resource\Provider\Node\NodeBaseAbstract;
 
 /**
- * Abstract Chrono Collection Base Class
+ * Abstract Documents Collection Base Class
  * 
  * Provides common implementation for chrono collections
  * 
@@ -22,6 +23,10 @@ abstract class CollectionBase extends NodeBaseAbstract implements CollectionBase
 
     protected CollectionPropertiesBaseAbstract $properties;
 
+    protected function nodeIdentifier(): CollectionIdentifier {
+        return new CollectionIdentifier($this->data[static::PROPERTY_PROVIDER], $this->data[static::PROPERTY_SERVICE], (string) $this->data[static::PROPERTY_IDENTIFIER]);
+    }
+
     /**
      * @inheritDoc
      */

shared/lib/Documents/Collection/CollectionBaseInterface.php

@@ -7,7 +7,7 @@ declare(strict_types=1);
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-namespace KTXF\Resource\Documents\Collection;
+namespace KTXF\Documents\Collection;
 
 use KTXF\Resource\Provider\Node\NodeBaseInterface;
 

shared/lib/Documents/Collection/CollectionContent.php

@@ -7,7 +7,7 @@ declare(strict_types=1);
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-namespace KTXF\Resource\Documents\Collection;
+namespace KTXF\Documents\Collection;
 
 use JsonSerializable;
 

shared/lib/Documents/Collection/CollectionMutableAbstract.php

@@ -7,13 +7,14 @@ declare(strict_types=1);
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-namespace KTXF\Resource\Documents\Collection;
+namespace KTXF\Documents\Collection;
 
+use KTXF\Resource\Identifier\CollectionIdentifier;
 use KTXF\Resource\Provider\Node\NodeMutableAbstract;
 use KTXF\Resource\Provider\Node\NodePropertiesMutableInterface;
 
 /**
- * Abstract Chrono Collection Mutable Class
+ * Abstract Documents Collection Mutable Class
  * 
  * Provides common implementation for mutable chrono collections
  * 
@@ -23,6 +24,10 @@ abstract class CollectionMutableAbstract extends NodeMutableAbstract implements
 
     protected CollectionPropertiesMutableAbstract $properties;
 
+    protected function nodeIdentifier(): CollectionIdentifier {
+        return new CollectionIdentifier($this->data[static::PROPERTY_PROVIDER], $this->data[static::PROPERTY_SERVICE], (string) $this->data[static::PROPERTY_IDENTIFIER]);
+    }
+
     /**
      * @inheritDoc
      */

shared/lib/Documents/Collection/CollectionMutableInterface.php

@@ -7,12 +7,12 @@ declare(strict_types=1);
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-namespace KTXF\Resource\Documents\Collection;
+namespace KTXF\Documents\Collection;
 
 use KTXF\Resource\Provider\Node\NodeMutableInterface;
 
 /**
- * Chrono Collection Mutable Interface
+ * Documents Collection Mutable Interface
  * 
  * Interface for altering collection properties in a chrono service
  * 

shared/lib/Documents/Collection/CollectionPropertiesBaseAbstract.php

@@ -7,7 +7,7 @@ declare(strict_types=1);
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-namespace KTXF\Resource\Documents\Collection;
+namespace KTXF\Documents\Collection;
 
 use KTXF\Resource\Provider\Node\NodePropertiesBaseAbstract;
 

shared/lib/Documents/Collection/CollectionPropertiesBaseInterface.php

@@ -7,7 +7,7 @@ declare(strict_types=1);
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-namespace KTXF\Resource\Documents\Collection;
+namespace KTXF\Documents\Collection;
 
 use KTXF\Resource\Provider\Node\NodePropertiesBaseInterface;
 

shared/lib/Documents/Collection/CollectionPropertiesMutableAbstract.php

@@ -7,10 +7,10 @@ declare(strict_types=1);
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-namespace KTXF\Resource\Documents\Collection;
+namespace KTXF\Documents\Collection;
 
 /**
- * Abstract Chrono Collection Properties Mutable Class
+ * Abstract Documents Collection Properties Mutable Class
  */
 abstract class CollectionPropertiesMutableAbstract extends CollectionPropertiesBaseAbstract implements CollectionPropertiesMutableInterface {
 

shared/lib/Documents/Collection/CollectionPropertiesMutableInterface.php

@@ -7,7 +7,7 @@ declare(strict_types=1);
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-namespace KTXF\Resource\Documents\Collection;
+namespace KTXF\Documents\Collection;
 
 use KTXF\Resource\Provider\Node\NodePropertiesMutableInterface;
 

shared/lib/Documents/Entity/EntityBaseAbstract.php

@@ -7,12 +7,13 @@ declare(strict_types=1);
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-namespace KTXF\Resource\Documents\Entity;
+namespace KTXF\Documents\Entity;
 
+use KTXF\Resource\Identifier\EntityIdentifier;
 use KTXF\Resource\Provider\Node\NodeBaseAbstract;
 
 /**
- * Abstract Chrono Entity Base Class
+ * Abstract Documents Entity Base Class
  * 
  * Provides common implementation for chrono entities
  * 
@@ -22,6 +23,10 @@ abstract class EntityBaseAbstract extends NodeBaseAbstract implements EntityBase
 
     protected EntityPropertiesBaseAbstract $properties;
 
+    protected function nodeIdentifier(): EntityIdentifier {
+        return new EntityIdentifier($this->data[static::PROPERTY_PROVIDER], $this->data[static::PROPERTY_SERVICE], (string) $this->data[static::PROPERTY_COLLECTION], (string) $this->data[static::PROPERTY_IDENTIFIER]);
+    }
+
     /**
      * @inheritDoc
      */

shared/lib/Documents/Entity/EntityBaseInterface.php

@@ -7,7 +7,7 @@ declare(strict_types=1);
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-namespace KTXF\Resource\Documents\Entity;
+namespace KTXF\Documents\Entity;
 
 use KTXF\Resource\Provider\Node\NodeBaseInterface;
 

shared/lib/Documents/Entity/EntityMutableAbstract.php

@@ -7,13 +7,14 @@ declare(strict_types=1);
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-namespace KTXF\Resource\Documents\Entity;
+namespace KTXF\Documents\Entity;
 
+use KTXF\Resource\Identifier\EntityIdentifier;
 use KTXF\Resource\Provider\Node\NodeMutableAbstract;
 use KTXF\Resource\Provider\Node\NodePropertiesMutableInterface;
 
 /**
- * Abstract Chrono Entity Mutable Class
+ * Abstract Documents Entity Mutable Class
  * 
  * Provides common implementation for mutable chrono entities
  * 
@@ -25,6 +26,10 @@ abstract class EntityMutableAbstract extends NodeMutableAbstract implements Enti
 
     protected EntityPropertiesMutableAbstract $properties;
 
+    protected function nodeIdentifier(): EntityIdentifier {
+        return new EntityIdentifier($this->data[static::PROPERTY_PROVIDER], $this->data[static::PROPERTY_SERVICE], (string) $this->data[static::PROPERTY_COLLECTION], (string) $this->data[static::PROPERTY_IDENTIFIER]);
+    }
+
     /**
      * @inheritDoc
      */

shared/lib/Documents/Entity/EntityMutableInterface.php

@@ -7,7 +7,7 @@ declare(strict_types=1);
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-namespace KTXF\Resource\Documents\Entity;
+namespace KTXF\Documents\Entity;
 
 use KTXF\Resource\Provider\Node\NodeMutableInterface;
 

shared/lib/Documents/Entity/EntityPropertiesBaseAbstract.php

@@ -7,7 +7,7 @@ declare(strict_types=1);
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-namespace KTXF\Resource\Documents\Entity;
+namespace KTXF\Documents\Entity;
 
 use KTXF\Resource\Provider\Node\NodePropertiesBaseAbstract;
 

shared/lib/Documents/Entity/EntityPropertiesBaseInterface.php

@@ -7,7 +7,7 @@ declare(strict_types=1);
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-namespace KTXF\Resource\Documents\Entity;
+namespace KTXF\Documents\Entity;
 
 use KTXF\Resource\Provider\Node\NodePropertiesBaseInterface;
 

shared/lib/Documents/Entity/EntityPropertiesMutableAbstract.php

@@ -7,7 +7,7 @@ declare(strict_types=1);
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-namespace KTXF\Resource\Documents\Entity;
+namespace KTXF\Documents\Entity;
 
 abstract class EntityPropertiesMutableAbstract extends EntityPropertiesBaseAbstract implements EntityPropertiesMutableInterface {
 

shared/lib/Documents/Entity/EntityPropertiesMutableInterface.php

@@ -7,7 +7,7 @@ declare(strict_types=1);
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-namespace KTXF\Resource\Documents\Entity;
+namespace KTXF\Documents\Entity;
 
 use KTXF\Resource\Provider\Node\NodePropertiesMutableInterface;
 

shared/lib/Documents/Provider/ProviderBaseInterface.php

@@ -7,17 +7,17 @@ declare(strict_types=1);
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-namespace KTXF\Resource\Documents\Provider;
+namespace KTXF\Documents\Provider;
 
 use KTXF\Resource\Provider\ResourceProviderBaseInterface;
 
 /**
- * Chrono Provider Base Interface
+ * Provider Base Interface
- * 
+ *
  * @since 2025.05.01
  */
 interface ProviderBaseInterface extends ResourceProviderBaseInterface{
 
     public const JSON_TYPE = 'document:provider';
-    
+
 }

shared/lib/Documents/Provider/ProviderServiceMutateInterface.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Documents\Provider;
+
+use KTXF\Resource\Provider\ResourceProviderServiceMutateInterface;
+
+/**
+ * Provider Service Mutate Interface
+ *
+ * Optional interface for providers that support service CRUD operations
+ *
+ * @since 2025.05.01
+ *
+ * @method ServiceMutableInterface serviceFresh() Construct a new blank documents service instance
+ * @method string serviceCreate(string $tenantId, ?string $userId, ServiceMutableInterface $service) Create a documents service configuration
+ * @method string serviceModify(string $tenantId, ?string $userId, ServiceMutableInterface $service) Modify a documents service configuration
+ * @method bool serviceDestroy(string $tenantId, ?string $userId, ServiceMutableInterface $service) Delete a documents service configuration
+ */
+interface ProviderServiceMutateInterface extends ResourceProviderServiceMutateInterface {
+
+    // Methods inherited from ResourceProviderServiceMutateInterface
+
+}

shared/lib/Documents/Provider/ProviderServiceTestInterface.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Documents\Provider;
+
+use KTXF\Documents\Service\ServiceBaseInterface;
+use KTXF\Documents\Service\ServiceMutableInterface;
+
+/**
+ * Provider Service Test Interface
+ *
+ * Optional interface for providers that support testing service connections
+ *
+ * @since 2025.05.01
+ */
+interface ProviderServiceTestInterface {
+
+    public const CAPABILITY_SERVICE_TEST = 'ServiceTest';
+
+    /**
+     * Test a service connection
+     *
+     * Tests connectivity, authentication, and capabilities of a service
+     *
+     * @since 2025.05.01
+     *
+     * @param ServiceBaseInterface|ServiceMutableInterface $service Service to test (can be fresh/unsaved or existing)
+     * @param array $options Provider-specific test options:
+     *   - 'timeout' => int (seconds, default: 10)
+     *   - 'verify_ssl' => bool (default: true)
+     *
+     * @return array Test results in the format:
+     * [
+     *   'disposition' => 'Success' | 'Failure' | 'Warning',
+     *   'message' => 'Connection successful' | 'Error message',
+     * ]
+     */
+    public function serviceTest(ServiceBaseInterface|ServiceMutableInterface $service, array $options = []): array;
+
+}

shared/lib/Documents/Service/ServiceBaseInterface.php

@@ -7,19 +7,24 @@ declare(strict_types=1);
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-namespace KTXF\Resource\Documents\Service;
+namespace KTXF\Documents\Service;
 
-use KTXF\Resource\Documents\Collection\CollectionBaseInterface;
+use Generator;
+use KTXF\Documents\Collection\CollectionBaseInterface;
+use KTXF\Documents\Entity\EntityBaseInterface;
 use KTXF\Resource\Delta\Delta;
 use KTXF\Resource\Filter\IFilter;
+use KTXF\Resource\Identifier\EntityIdentifierInterface;
 use KTXF\Resource\Provider\ResourceServiceBaseInterface;
 use KTXF\Resource\Range\IRange;
 use KTXF\Resource\Range\RangeType;
 use KTXF\Resource\Sort\ISort;
 
 /**
- * Chrono Service Base Interface
+ * Service Base Interface
- * 
+ *
+ * Minimum interface for a service, providing read-only access to collections and entities.
+ *
  * @since 2025.05.01
  */
 interface ServiceBaseInterface extends ResourceServiceBaseInterface {
@@ -59,7 +64,6 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface {
     public const CAPABILITY_ENTITY_RANGE_TALLY = 'tally';
     public const CAPABILITY_ENTITY_RANGE_TALLY_ABSOLUTE = 'absolute';
     public const CAPABILITY_ENTITY_RANGE_TALLY_RELATIVE = 'relative';
-    public const CAPABILITY_ENTITY_RANGE_DATE = 'date';
 
     public const JSON_TYPE = 'document:service';
 
@@ -68,11 +72,11 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface {
      *
      * @since 2025.05.01
      *
-     * @param string|int|null $location Optional parent collection ID to list within
+     * @param string|int|null $location Optional parent collection identifier to list within (null for root)
      * @param IFilter|null $filter Optional filter criteria
      * @param ISort|null $sort Optional sort order
      *
-     * @return array<string|int,CollectionBaseInterface> Collections indexed by ID
+     * @return array<string|int,CollectionBaseInterface> Collections indexed by identifier
      */
     public function collectionList(string|int|null $location, ?IFilter $filter = null, ?ISort $sort = null): array;
 
@@ -99,9 +103,10 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface {
      *
      * @since 2025.05.01
      *
-     * @param string|int ...$identifiers Collection IDs to check
+     * @param string|int|null $location Optional parent collection identifier (null for root)
+     * @param string|int ...$identifiers Collection identifiers to check
      *
-     * @return array<string|int,bool> Map of ID => exists
+     * @return array<string|int,bool> Map of identifier => exists
      */
     public function collectionExtant(string|int|null $location, string|int ...$identifiers): array;
 
@@ -110,26 +115,41 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface {
      *
      * @since 2025.05.01
      *
-     * @param string|int $identifier Collection ID
+     * @param string|int $identifier Collection identifier
      *
      * @return CollectionBaseInterface|null Collection or null if not found
      */
-    public function collectionFetch(string|int|null $identifier): ?CollectionBaseInterface;
+    public function collectionFetch(string|int $identifier): ?CollectionBaseInterface;
 
     /**
-     * Lists messages in a collection
+     * Lists entities in a collection
      *
      * @since 2025.05.01
      *
-     * @param string|int|null $collection Collection ID
+     * @param string|int|null $collection Collection identifier (null for root)
      * @param IFilter|null $filter Optional filter criteria
      * @param ISort|null $sort Optional sort order
      * @param IRange|null $range Optional pagination
-     * @param array|null $properties Optional message properties to fetch
+     * @param array|null $properties Optional entity properties to fetch
      *
-     * @return array<string|int,EntityBaseInterface> Messages indexed by ID
+     * @return array<string|int,EntityBaseInterface> Entities indexed by identifier
      */
-    public function entityList(string|int|null $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): array;
+    public function entityListBulk(string|int|null $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): array;
+
+    /**
+     * Lists entities in a collection
+     *
+     * @since 2025.05.01
+     *
+     * @param string|int|null $collection Collection identifier (null for root)
+     * @param IFilter|null $filter Optional filter criteria
+     * @param ISort|null $sort Optional sort order
+     * @param IRange|null $range Optional pagination
+     * @param array|null $properties Optional entity properties to fetch
+     *
+     * @return Generator Yields entities one by one as EntityBaseInterface
+     */
+    public function entityListStream(string|int|null $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): Generator;
 
     /**
      * Creates a filter builder for entities
@@ -161,98 +181,84 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface {
     public function entityListRange(RangeType $type): IRange;
 
     /**
-     * Gets incremental changes since last sync
+     * Gets incremental changes since last signature
      *
      * @since 2025.05.01
      *
-     * @param string|int|null $collection Collection ID
+     * @param string|int|null $collection Collection identifier (null for root)
-     * @param string $signature Sync token from previous sync
+     * @param string $signature Token from previous delta
-     * @param string $detail Detail level: 'ids', 'minimal', 'full'
      *
-     * @return array ['signature' => string, 'added' => array, 'modified' => array, 'removed' => array]
+     * @return Delta
      */
-    public function entityDelta(string|int|null $collection, string $signature, string $detail = 'ids'): Delta;
+    public function entityDelta(string|int|null $collection, string $signature): Delta;
 
     /**
-     * Checks if messages exist
+     * Checks if entities exist
      *
      * @since 2025.05.01
      *
-     * @param string|int $collection Collection ID
+     * @param string|int|null $collection Collection identifier (null for root)
-     * @param string|int ...$identifiers Message IDs to check
+     * @param string|int ...$identifiers Entity identifiers to check
      *
-     * @return array<string|int,bool> Map of ID => exists
+     * @return array<string|int,bool> Map of identifier => exists
      */
     public function entityExtant(string|int|null $collection, string|int ...$identifiers): array;
 
     /**
-     * Fetches one or more entities
+     * Fetches one or more entities as an array
      *
      * @since 2025.05.01
      *
-     * @param string|int $collection Collection ID
+     * @param EntityIdentifierInterface ...$identifiers Entity identifiers to fetch
-     * @param string|int ...$identifiers Message IDs to fetch
      *
-     * @return array<string|int,EntityBaseInterface> Messages indexed by ID
+     * @return array<string|int,EntityBaseInterface> Entities indexed by identifier
      */
-    public function entityFetch(string|int|null $collection, string|int ...$identifiers): array;
+    public function entityFetchBulk(EntityIdentifierInterface ...$identifiers): array;
 
     /**
-     * Reads the content of an entity
+     * Fetches one or more entities as a stream
      *
      * @since 2025.05.01
      *
-     * @param string|int|null $collection Collection ID
+     * @param EntityIdentifierInterface ...$identifiers Entity identifiers to fetch
-     * @param string|int $identifier Entity ID
+     *
+     * @return Generator<string|int,EntityBaseInterface> Yields entities one by one
+     */
+    public function entityFetchStream(EntityIdentifierInterface ...$identifiers): Generator;
+
+    /**
+     * Reads the full content of an entity
+     *
+     * @since 2025.05.01
+     *
+     * @param EntityIdentifierInterface $target Target entity identifier
      *
      * @return string|null Entity content or null if not found
      */
-    public function entityRead(string|int|null $collection, string|int $identifier): ?string;
+    public function entityRead(EntityIdentifierInterface $target): ?string;
 
     /**
-     * Lists messages in a collection
+     * Opens a read stream for the content of an entity
      *
      * @since 2025.05.01
      *
-     * @param string|int|null $collection Collection ID
+     * @param EntityIdentifierInterface $target Target entity identifier
-     * @param IFilter|null $filter Optional filter criteria
-     * @param ISort|null $sort Optional sort order
-     * @param IRange|null $range Optional pagination
-     * @param array|null $properties Optional message properties to fetch
      *
-     * @return array<string|int,CollectionBaseInterface|EntityBaseInterface> Nodes indexed by ID
+     * @return resource|null Read stream or null if not found
      */
-    public function nodeList(string|int|null $collection, bool $recursive = false, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): array;
+    public function entityReadStream(EntityIdentifierInterface $target);
 
     /**
-     * Creates a filter builder for nodes
+     * Reads a chunk of the content of an entity
      *
      * @since 2025.05.01
      *
-     * @return IFilter
+     * @param EntityIdentifierInterface $target Target entity identifier
+     * @param int $offset Byte offset to start reading from
+     * @param int $length Number of bytes to read
+     *
+     * @return string|null Content chunk or null if not found
      */
-    public function nodeListFilter(): IFilter;
+    public function entityReadChunk(EntityIdentifierInterface $target, int $offset, int $length): ?string;
-
-    /**
-     * Creates a sort builder for nodes
-     *
-     * @since 2025.05.01
-     *
-     * @return ISort
-     */
-    public function nodeListSort(): ISort;
-
-    /**
-     * Gets incremental changes since last sync
-     *
-     * @since 2025.05.01
-     *
-     * @param string|int|null $collection Collection ID
-     * @param string $signature Sync token from previous sync
-     * @param string $detail Detail level: 'ids', 'minimal', 'full'
-     *
-     * @return array ['signature' => string, 'added' => array, 'modified' => array, 'removed' => array]
-     */
-    public function nodeDelta(string|int|null $collection, string $signature, string $detail = 'ids'): Delta;
 
 }

shared/lib/Documents/Service/ServiceCollectionMutableInterface.php

@@ -0,0 +1,102 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Documents\Service;
+
+use KTXF\Documents\Collection\CollectionBaseInterface;
+use KTXF\Documents\Collection\CollectionMutableInterface;
+use KTXF\Documents\Collection\CollectionPropertiesBaseInterface;
+use KTXF\Resource\Identifier\CollectionIdentifierInterface;
+
+/**
+ * Service Collection Mutable Interface
+ *
+ * Optional interface for services that support collection CRUD operations.
+ *
+ * @since 2025.05.01
+ */
+interface ServiceCollectionMutableInterface {
+
+    public const CAPABILITY_COLLECTION_CREATE = 'CollectionCreate';
+    public const CAPABILITY_COLLECTION_UPDATE = 'CollectionUpdate';
+    public const CAPABILITY_COLLECTION_DELETE = 'CollectionDelete';
+    public const CAPABILITY_COLLECTION_MOVE = 'CollectionMove';
+    public const CAPABILITY_COLLECTION_COPY = 'CollectionCopy';
+
+    /**
+     * Creates a fresh collection instance for configuration
+     *
+     * @since 2025.05.01
+     *
+     * @return CollectionMutableInterface Fresh collection object
+     */
+    public function collectionFresh(): CollectionMutableInterface;
+
+    /**
+     * Creates a new collection
+     *
+     * @since 2025.05.01
+     *
+     * @param CollectionIdentifierInterface|null $target Target collection identifier (parent, null for root)
+     * @param CollectionPropertiesBaseInterface $properties Collection properties
+     * @param array $options Protocol-specific options
+     *
+     * @return CollectionBaseInterface Created collection with assigned ID
+     */
+    public function collectionCreate(CollectionIdentifierInterface|null $target, CollectionPropertiesBaseInterface $properties, array $options = []): CollectionBaseInterface;
+
+    /**
+     * Updates an existing collection
+     *
+     * @since 2025.05.01
+     *
+     * @param CollectionIdentifierInterface $target Target collection identifier
+     * @param CollectionPropertiesBaseInterface $properties Updated collection data
+     *
+     * @return CollectionBaseInterface Updated collection
+     */
+    public function collectionUpdate(CollectionIdentifierInterface $target, CollectionPropertiesBaseInterface $properties): CollectionBaseInterface;
+
+    /**
+     * Deletes a collection
+     *
+     * @since 2025.05.01
+     *
+     * @param CollectionIdentifierInterface $target Target collection identifier
+     * @param bool $force Force deletion even if not empty
+     *
+     * @return CollectionBaseInterface|true Collection object on soft delete, true on hard delete
+     */
+    public function collectionDelete(CollectionIdentifierInterface $target, bool $force = false): CollectionBaseInterface | true;
+
+    /**
+     * Moves a collection to a new parent
+     *
+     * @since 2025.05.01
+     *
+     * @param CollectionIdentifierInterface|null $target Target parent collection identifier (null for root)
+     * @param CollectionIdentifierInterface $source Source collection identifier
+     *
+     * @return CollectionBaseInterface Moved collection
+     */
+    public function collectionMove(CollectionIdentifierInterface|null $target, CollectionIdentifierInterface $source): CollectionBaseInterface;
+
+    /**
+     * Copies a collection to a new parent
+     *
+     * @since 2025.05.01
+     *
+     * @param CollectionIdentifierInterface|null $target Target parent collection identifier (null for root)
+     * @param CollectionIdentifierInterface $source Source collection identifier
+     *
+     * @return CollectionBaseInterface Copied collection
+     */
+    public function collectionCopy(CollectionIdentifierInterface|null $target, CollectionIdentifierInterface $source): CollectionBaseInterface;
+
+}

shared/lib/Documents/Service/ServiceConfigurableInterface.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Documents\Service;
+
+use KTXF\Resource\Provider\ResourceServiceConfigureInterface;
+
+/**
+ * Service Configurable Interface
+ *
+ * Extends base service interface with setter methods for mutable properties
+ *
+ * @since 2025.05.01
+ */
+interface ServiceConfigurableInterface extends ResourceServiceConfigureInterface {
+
+}

shared/lib/Documents/Service/ServiceEntityMutableInterface.php

@@ -0,0 +1,151 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Documents\Service;
+
+use KTXF\Documents\Entity\EntityBaseInterface;
+use KTXF\Documents\Entity\EntityMutableInterface;
+use KTXF\Documents\Entity\EntityPropertiesMutableInterface;
+use KTXF\Resource\Identifier\CollectionIdentifierInterface;
+use KTXF\Resource\Identifier\EntityIdentifierInterface;
+
+/**
+ * Service Entity Mutable Interface
+ *
+ * Optional interface for services that support entity CRUD operations
+ *
+ * @since 2025.05.01
+ */
+interface ServiceEntityMutableInterface {
+
+    public const CAPABILITY_ENTITY_CREATE = 'EntityCreate';
+    public const CAPABILITY_ENTITY_MODIFY = 'EntityModify';
+    public const CAPABILITY_ENTITY_DELETE = 'EntityDelete';
+    public const CAPABILITY_ENTITY_COPY = 'EntityCopy';
+    public const CAPABILITY_ENTITY_MOVE = 'EntityMove';
+    public const CAPABILITY_ENTITY_WRITE = 'EntityWrite';
+
+    /**
+     * Creates a fresh entity instance for composition
+     *
+     * @since 2025.05.01
+     *
+     * @return EntityMutableInterface Fresh entity object
+     */
+    public function entityFresh(): EntityMutableInterface;
+
+    /**
+     * Creates/imports an entity into a collection
+     *
+     * @since 2025.05.01
+     *
+     * @param CollectionIdentifierInterface $target Target collection identifier
+     * @param EntityPropertiesMutableInterface $properties Entity properties
+     * @param array $options Additional options
+     *
+     * @return EntityBaseInterface Created entity
+     */
+    public function entityCreate(CollectionIdentifierInterface $target, EntityPropertiesMutableInterface $properties, array $options = []): EntityBaseInterface;
+
+    /**
+     * Modifies an existing entity
+     *
+     * @since 2025.05.01
+     *
+     * @param EntityIdentifierInterface $target Target entity identifier
+     * @param EntityPropertiesMutableInterface $properties Entity properties to update
+     *
+     * @return EntityBaseInterface Modified entity
+     */
+    public function entityModify(EntityIdentifierInterface $target, EntityPropertiesMutableInterface $properties): EntityBaseInterface;
+
+    /**
+     * Deletes entities
+     *
+     * @since 2026.04.01
+     *
+     * @param EntityIdentifierInterface ...$targets Source entities to delete
+     *
+     * @return array<string, array{
+     *     disposition: 'deleted'|'error',
+     *     destination: ?CollectionIdentifierInterface,
+     *     mutation: EntityIdentifierInterface
+     * }> Results keyed by source entity identifier
+     */
+    public function entityDelete(EntityIdentifierInterface ...$targets): array;
+
+    /**
+     * Moves entities to another collection
+     *
+     * @since 2025.05.01
+     *
+     * @param CollectionIdentifierInterface $target Target collection identifier
+     * @param EntityIdentifierInterface ...$sources Source entities to move
+     *
+     * @return array<string, array{
+     *     disposition: 'moved'|'error',
+     *     destination: ?CollectionIdentifierInterface,
+     *     mutation: EntityIdentifierInterface
+     * }> Results keyed by source entity identifier
+     */
+    public function entityMove(CollectionIdentifierInterface $target, EntityIdentifierInterface ...$sources): array;
+
+    /**
+     * Copies entities to another collection
+     *
+     * @since 2025.05.01
+     *
+     * @param CollectionIdentifierInterface $target Target collection identifier
+     * @param EntityIdentifierInterface ...$sources Source entities to copy
+     *
+     * @return array<string, array{
+     *     disposition: 'copied'|'error',
+     *     destination: ?CollectionIdentifierInterface,
+     *     mutation: EntityIdentifierInterface
+     * }> Results keyed by source entity identifier
+     */
+    public function entityCopy(CollectionIdentifierInterface $target, EntityIdentifierInterface ...$sources): array;
+
+    /**
+     * Writes the full content of an entity
+     *
+     * @since 2025.05.01
+     *
+     * @param EntityIdentifierInterface $target Target entity identifier
+     * @param string $data Content to write
+     *
+     * @return int Number of bytes written
+     */
+    public function entityWrite(EntityIdentifierInterface $target, string $data): int;
+
+    /**
+     * Writes a chunk of content to an entity
+     *
+     * @since 2025.05.01
+     *
+     * @param EntityIdentifierInterface $target Target entity identifier
+     * @param int $offset Byte offset to start writing at
+     * @param string $data Content chunk to write
+     *
+     * @return int Number of bytes written
+     */
+    public function entityWriteChunk(EntityIdentifierInterface $target, int $offset, string $data): int;
+
+    /**
+     * Opens a write stream for the content of an entity
+     *
+     * @since 2025.05.01
+     *
+     * @param EntityIdentifierInterface $target Target entity identifier
+     *
+     * @return resource|null Write stream or null if not found
+     */
+    public function entityWriteStream(EntityIdentifierInterface $target);
+
+}

shared/lib/Documents/Service/ServiceMutableInterface.php

@@ -7,18 +7,17 @@ declare(strict_types=1);
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-namespace KTXF\Resource\Documents\Service;
+namespace KTXF\Documents\Service;
 
 use KTXF\Resource\Provider\ResourceServiceMutateInterface;
 
 /**
- * Documents Service Mutable Interface
+ * Service Mutable Interface
- * 
+ *
- * Extends base service interface with setter methods for mutable properties.
+ * Extends base service interface with setter methods for mutable properties
- * Used for service configuration and updates.
+ *
- * 
  * @since 2025.05.01
  */
-interface ServiceMutableInterface extends ServiceBaseInterface, ResourceServiceMutateInterface {
+interface ServiceMutableInterface extends ResourceServiceMutateInterface {
 
 }

shared/lib/Resource/Documents/Provider/ProviderServiceMutateInterface.php

@@ -1,35 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-/**
- * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
- * SPDX-License-Identifier: AGPL-3.0-or-later
- */
-
-namespace KTXF\Resource\Documents\Provider;
-
-use KTXF\Resource\Provider\ResourceProviderServiceMutateInterface;
-
-/**
- * Chrono Provider Service Mutate Interface
- * 
- * Optional interface for providers that support service CRUD operations.
- * 
- * Implementations return ServiceMutableInterface instances (which extend ResourceServiceMutateInterface).
- * 
- * @since 2025.05.01
- * 
- * @method ServiceMutableInterface serviceFresh() Construct a new blank chrono service instance
- * @method string serviceCreate(string $tenantId, ?string $userId, ServiceMutableInterface $service) Create a chrono service configuration
- * @method string serviceModify(string $tenantId, ?string $userId, ServiceMutableInterface $service) Modify a chrono service configuration
- * @method bool serviceDestroy(string $tenantId, ?string $userId, ServiceMutableInterface $service) Delete a chrono service configuration
- */
-interface ProviderServiceMutateInterface extends ProviderBaseInterface, ResourceProviderServiceMutateInterface {
-
-    public const JSON_TYPE = ProviderBaseInterface::JSON_TYPE;
-
-	// Methods inherited from ResourceProviderServiceMutateInterface
-	// Implementations should return/accept ServiceMutableInterface instances
-
-}

shared/lib/Resource/Documents/Provider/ProviderServiceTestInterface.php

@@ -1,57 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-/**
- * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
- * SPDX-License-Identifier: AGPL-3.0-or-later
- */
-
-namespace KTXF\Resource\Documents\Provider;
-
-use KTXF\Resource\Documents\Service\ServiceBaseInterface;
-
-/**
- * Chrono Provider Service Test Interface
- * 
- * Optional interface for chrono providers that support testing service connections.
- * Providers implementing this interface can validate connection parameters,
- * test authentication, and verify service availability before creating a
- * persistent service configuration.
- * 
- * Supports two testing modes:
- * 1. Testing an existing service (validate current configuration)
- * 2. Testing a fresh configuration (validate before saving)
- * 
- * @since 2025.05.01
- */
-interface ProviderServiceTestInterface extends ProviderBaseInterface {
-
-    /**
-     * Test a service connection
-     * 
-     * Tests connectivity, authentication, and capabilities of a service.
-     * 
-     * For new services: use serviceFresh() to create a service, configure it with
-     * setters, then pass it to this method for testing before persisting.
-     * 
-     * For existing services: fetch the service and pass it directly.
-     * 
-     * @since 2025.05.01
-     * 
-     * @param ServiceBaseInterface $service Service to test (can be fresh/unsaved or existing)
-     * @param array $options Provider-specific test options:
-     *   - 'timeout' => int (seconds, default: 10)
-     *   - 'verify_ssl' => bool (default: true)
-     *   - 'test_send' => bool (attempt test send if capable, default: false)
-     *   - 'test_receive' => bool (attempt mailbox access if capable, default: true)
-     * 
-     * @return array Test results in the format:
-     * [
-     *   'success' => bool,
-     *   'message' => 'Connection successful' | 'Error message'
-     * ]
-     */
-    public function serviceTest(ServiceBaseInterface $service, array $options = []): array;
-
-}

shared/lib/Resource/Documents/Service/ServiceCollectionMutableInterface.php

@@ -1,73 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-/**
- * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
- * SPDX-License-Identifier: AGPL-3.0-or-later
- */
-
-namespace KTXF\Resource\Documents\Service;
-
-use KTXF\Resource\Documents\Collection\CollectionBaseInterface;
-use KTXF\Resource\Documents\Collection\CollectionMutableInterface;
-
-/**
- * Chrono Service Collection Mutable Interface
- * 
- * @since 2025.05.01
- */
-interface ServiceCollectionMutableInterface extends ServiceBaseInterface {
-
-    public const CAPABILITY_COLLECTION_CREATE = 'CollectionCreate';
-    public const CAPABILITY_COLLECTION_UPDATE = 'CollectionUpdate';
-    public const CAPABILITY_COLLECTION_DELETE = 'CollectionDelete';
-
-    /**
-     * Creates a fresh collection instance for configuration
-     *
-     * @since 2025.05.01
-     *
-     * @return CollectionMutableInterface Fresh collection object
-     */
-    public function collectionFresh(): CollectionMutableInterface;
-
-    /**
-     * Creates a new collection
-     *
-     * @since 2025.05.01
-     *
-     * @param string|int|null $location Parent collection ID (null for root)
-     * @param CollectionMutableInterface $collection Collection to create
-     * @param array $options Protocol-specific options
-     *
-     * @return CollectionBaseInterface Created collection with assigned ID
-     */
-    public function collectionCreate(string|int|null $location, CollectionMutableInterface $collection, array $options = []): CollectionBaseInterface;
-
-    /**
-     * Updates an existing collection
-     *
-     * @since 2025.05.01
-     *
-     * @param string|int $identifier Collection ID
-     * @param CollectionMutableInterface $collection Updated collection data
-     *
-     * @return CollectionBaseInterface Updated collection
-     */
-    public function collectionUpdate(string|int $identifier, CollectionMutableInterface $collection): CollectionBaseInterface;
-
-    /**
-     * Deletes a collection
-     *
-     * @since 2025.05.01
-     *
-     * @param string|int $identifier Collection ID
-     * @param bool $force Force deletion even if not empty
-     * @param bool $recursive Recursively delete contents
-     *
-     * @return bool True if deleted
-     */
-    public function collectionDelete(string|int $identifier, bool $force = false, bool $recursive = false): bool;
-
-}

shared/lib/Resource/Documents/Service/ServiceConfigurableInterface.php

@@ -1,26 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-/**
- * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
- * SPDX-License-Identifier: AGPL-3.0-or-later
- */
-
-namespace KTXF\Resource\Documents\Service;
-
-use KTXF\Resource\Provider\ResourceServiceConfigureInterface;
-
-/**
- * Chrono Service Configurable Interface
- * 
- * Extends base service interface with setter methods for mutable properties.
- * Used for service configuration and updates.
- * 
- * @since 2025.05.01
- */
-interface ServiceConfigurableInterface extends ServiceMutableInterface, ResourceServiceConfigureInterface {
-
-	public const JSON_TYPE = ServiceBaseInterface::JSON_TYPE;
-
-}

shared/lib/Resource/Documents/Service/ServiceEntityMutableInterface.php

@@ -1,83 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-/**
- * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
- * SPDX-License-Identifier: AGPL-3.0-or-later
- */
-
-namespace KTXF\Resource\Documents\Service;
-
-use KTXF\Resource\Documents\Entity\EntityBaseInterface;
-use KTXF\Resource\Documents\Entity\EntityMutableInterface;
-
-/**
- * Chrono Service Entity Mutable Interface
- * 
- * Optional interface for services that support entity CRUD operations.
- * Provides entity creation, modification, deletion, copying, moving, and flag management.
- * 
- * @since 2025.05.01
- */
-interface ServiceEntityMutableInterface extends ServiceBaseInterface {
-
-    public const CAPABILITY_ENTITY_CREATE = 'EntityCreate';
-    public const CAPABILITY_ENTITY_UPDATE = 'EntityUpdate';
-    public const CAPABILITY_ENTITY_DELETE = 'EntityDelete';
-    public const CAPABILITY_ENTITY_COPY = 'EntityCopy';
-    public const CAPABILITY_ENTITY_MOVE = 'EntityMove';
-    public const CAPABILITY_ENTITY_WRITE = 'EntityWrite';
-
-    /**
-     * Creates a fresh entity instance for composition
-     *
-     * @since 2025.05.01
-     *
-     * @return EntityMutableInterface Fresh entity object
-     */
-    public function entityFresh(): EntityMutableInterface;
-
-    /**
-     * Creates/imports an entity into a collection
-     *
-     * @since 2025.05.01
-     *
-     * @param string|int $collection collection identifier
-     * @param EntityMutableInterface $entity Entity data
-     * @param array $options additional options
-     *
-     * @return EntityBaseInterface Created entity
-     */
-    public function entityCreate(string|int|null $collection, EntityMutableInterface $entity, array $options = []): EntityBaseInterface;
-
-    /**
-     * Modifies an existing entity
-     *
-     * @since 2025.05.01
-     *
-     * @param string|int $collection Collection identifier
-     * @param string|int $identifier Entity identifier
-     * @param EntityMutableInterface $entity Entity data
-     *
-     * @return EntityBaseInterface Modified entity
-     */
-    public function entityUpdate(string|int|null $collection, string|int $identifier, EntityMutableInterface $entity): EntityBaseInterface;
-
-    /**
-     * Deletes an existing entity in the specified collection
-     *
-     * @since 2025.05.01
-     *
-     * @param string|int $collection Collection identifier
-     * @param string|int $identifier Entity identifier to delete
-     *
-     * @return EntityBaseInterface Deleted entity
-     */
-    public function entityDelete(string|int|null $collection, string|int $identifier): EntityBaseInterface;
-
-    /**
-     * 
-     */
-    public function entityWrite(string|int|null $collection, string|int $identifier, string $data): int;
-}