Initial Version

shared/lib/Files/Node/INodeBase.php

@@ -0,0 +1,105 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Files\Node;
+
+use DateTimeImmutable;
+
+interface INodeBase extends \JsonSerializable {
+
+	public const JSON_TYPE = 'files.node';
+	public const JSON_PROPERTY_TYPE = '@type';
+	public const JSON_PROPERTY_IN = 'in';
+	public const JSON_PROPERTY_ID = 'id';
+	public const JSON_PROPERTY_CREATED_ON = 'createdOn';
+	public const JSON_PROPERTY_CREATED_BY = 'createdBy';
+	public const JSON_PROPERTY_MODIFIED_ON = 'modifiedOn';
+	public const JSON_PROPERTY_MODIFIED_BY = 'modifiedBy';
+	public const JSON_PROPERTY_OWNER = 'owner';
+	public const JSON_PROPERTY_SIGNATURE = 'signature';
+	public const JSON_PROPERTY_LABEL = 'label';
+
+	/**
+	 * Unique identifier of the parent node (folder) this node belongs to
+	 *
+	 * @since 2025.11.01
+	 */
+	public function in(): string|int|null;
+
+	/**
+	 * Unique identifier of this node
+	 *
+	 * @since 2025.11.01
+	 */
+	public function id(): string|int;
+	
+	/**
+	 * Node type (collection or entity)
+	 *
+	 * @since 2025.11.01
+	 */
+	public function type(): NodeType;
+
+	/**
+	 * Creator user ID
+	 *
+	 * @since 2025.11.01
+	 */
+	public function createdBy(): string|null;
+	
+	/**
+	 * Creation timestamp
+	 *
+	 * @since 2025.11.01
+	 */
+	public function createdOn(): DateTimeImmutable|null;
+
+	/**
+	 * Last modifier user ID
+	 *
+	 * @since 2025.11.01
+	 */
+	public function modifiedBy(): string|null;
+
+	/**
+	 * Last modification timestamp
+	 *
+	 * @since 2025.11.01
+	 */
+	public function modifiedOn(): DateTimeImmutable|null;
+
+	/**
+	 * Signature/etag for sync and caching
+	 *
+	 * @since 2025.11.01
+	 */
+	public function signature(): string|null;
+
+	/**
+	 * Check if this node is a collection (folder)
+	 *
+	 * @since 2025.11.01
+	 */
+	public function isCollection(): bool;
+
+	/**
+	 * Check if this node is an entity (file)
+	 *
+	 * @since 2025.11.01
+	 */
+	public function isEntity(): bool;
+
+	/**
+	 * Human-readable name/label of this node
+	 *
+	 * @since 2025.11.01
+	 */
+	public function getLabel(): string|null;
+
+}

shared/lib/Files/Node/INodeCollectionBase.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Files\Node;
+
+/**
+ * Interface for collection (folder) nodes
+ * 
+ * Collections are containers that can hold other nodes (both collections and entities).
+ * They inherit common properties from INodeBase and add collection-specific properties.
+ */
+interface INodeCollectionBase extends INodeBase {
+
+	public const JSON_TYPE = 'files.collection';
+
+}

shared/lib/Files/Node/INodeCollectionMutable.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Files\Node;
+
+/**
+ * Interface for mutable collection (folder) nodes
+ */
+interface INodeCollectionMutable extends INodeCollectionBase {
+
+	/**
+	 * Deserialize from JSON data
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param array|string $data JSON data to deserialize
+	 *
+	 * @return static
+	 */
+	public function jsonDeserialize(array|string $data): static;
+
+	/**
+	 * Sets the human-readable name/label of this collection
+	 *
+	 * @since 2025.11.01
+	 */
+	public function setLabel(string $value): static;
+
+}

shared/lib/Files/Node/INodeEntityBase.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Files\Node;
+
+/**
+ * Interface for entity (file) nodes
+ * 
+ * Entities are leaf nodes that contain actual file data.
+ * They inherit common properties from INodeBase and add file-specific properties.
+ */
+interface INodeEntityBase extends INodeBase {
+
+	public const JSON_TYPE = 'files.entity';
+	public const JSON_PROPERTY_SIZE = 'size';
+	public const JSON_PROPERTY_MIME = 'mime';
+	public const JSON_PROPERTY_FORMAT = 'format';
+	public const JSON_PROPERTY_ENCODING = 'encoding';
+
+	/**
+	 * File size in bytes
+	 *
+	 * @since 2025.11.01
+	 */
+	public function size(): int;
+
+	/**
+	 * MIME type of the file (e.g., 'application/pdf', 'image/png')
+	 *
+	 * @since 2025.11.01
+	 */
+	public function getMime(): string|null;
+
+	/**
+	 * File format/extension (e.g., 'pdf', 'png', 'txt')
+	 *
+	 * @since 2025.11.01
+	 */
+	public function getFormat(): string|null;
+
+	/**
+	 * Character encoding (e.g., 'utf-8')
+	 *
+	 * @since 2025.11.01
+	 */
+	public function getEncoding(): string|null;
+
+}

shared/lib/Files/Node/INodeEntityMutable.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Files\Node;
+
+/**
+ * Interface for mutable entity (file) nodes
+ */
+interface INodeEntityMutable extends INodeEntityBase {
+
+	/**
+	 * Deserialize from JSON data
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param array|string $data JSON data to deserialize
+	 *
+	 * @return static
+	 */
+	public function jsonDeserialize(array|string $data): static;
+
+	/**
+	 * Sets the human-readable name/label of this entity
+	 *
+	 * @since 2025.11.01
+	 */
+	public function setLabel(string $value): static;
+
+	/**
+	 * Sets the MIME type of the file
+	 *
+	 * @since 2025.11.01
+	 */
+	public function setMime(string $value): static;
+
+	/**
+	 * Sets the file format/extension
+	 *
+	 * @since 2025.11.01
+	 */
+	public function setFormat(string $value): static;
+
+	/**
+	 * Sets the character encoding
+	 *
+	 * @since 2025.11.01
+	 */
+	public function setEncoding(string $value): static;
+
+}

shared/lib/Files/Node/NodeType.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\Files\Node;
+
+use JsonSerializable;
+
+enum NodeType: string implements JsonSerializable {
+
+    case Collection = 'C';
+    case Entity = 'E';
+
+    public function jsonSerialize(): string {
+        return $this->value;
+    }
+
+}

shared/lib/Files/Provider/IProviderBase.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Files\Provider;
+
+use KTXF\Resource\Provider\ResourceProviderInterface;
+
+interface IProviderBase extends ResourceProviderInterface {
+
+}

shared/lib/Files/Service/IServiceBase.php

@@ -0,0 +1,333 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Files\Service;
+
+use JsonSerializable;
+use KTXF\Files\Node\INodeBase;
+use KTXF\Files\Node\INodeCollectionBase;
+use KTXF\Files\Node\INodeEntityBase;
+use KTXF\Resource\Filter\IFilter;
+use KTXF\Resource\Range\IRange;
+use KTXF\Resource\Range\RangeType;
+use KTXF\Resource\Sort\ISort;
+
+interface IServiceBase extends JsonSerializable {
+
+	// Collection Capabilities
+	public const CAPABILITY_COLLECTION_LIST = 'CollectionList';
+	public const CAPABILITY_COLLECTION_LIST_FILTER = 'CollectionListFilter';
+	public const CAPABILITY_COLLECTION_LIST_SORT = 'CollectionListSort';
+	public const CAPABILITY_COLLECTION_EXTANT = 'CollectionExtant';
+	public const CAPABILITY_COLLECTION_FETCH = 'CollectionFetch';
+
+	// Entity Capabilities
+	public const CAPABILITY_ENTITY_LIST = 'EntityList';
+	public const CAPABILITY_ENTITY_LIST_FILTER = 'EntityListFilter';
+	public const CAPABILITY_ENTITY_LIST_SORT = 'EntityListSort';
+	public const CAPABILITY_ENTITY_LIST_RANGE = 'EntityListRange';
+	public const CAPABILITY_ENTITY_DELTA = 'EntityDelta';
+	public const CAPABILITY_ENTITY_EXTANT = 'EntityExtant';
+	public const CAPABILITY_ENTITY_FETCH = 'EntityFetch';
+	public const CAPABILITY_ENTITY_READ = 'EntityRead';
+	public const CAPABILITY_ENTITY_READ_STREAM = 'EntityReadStream';
+	public const CAPABILITY_ENTITY_READ_CHUNK = 'EntityReadChunk';
+
+	// Node Capabilities (recursive/unified)
+	public const CAPABILITY_NODE_LIST = 'NodeList';
+	public const CAPABILITY_NODE_LIST_FILTER = 'NodeListFilter';
+	public const CAPABILITY_NODE_LIST_SORT = 'NodeListSort';
+	public const CAPABILITY_NODE_LIST_RANGE = 'NodeListRange';
+	public const CAPABILITY_NODE_DELTA = 'NodeDelta';
+
+	// JSON Constants
+	public const JSON_TYPE = 'files.service';
+	public const JSON_PROPERTY_TYPE = '@type';
+	public const JSON_PROPERTY_PROVIDER = 'provider';
+	public const JSON_PROPERTY_ID = 'id';
+	public const JSON_PROPERTY_LABEL = 'label';
+	public const JSON_PROPERTY_CAPABILITIES = 'capabilities';
+	public const JSON_PROPERTY_ENABLED = 'enabled';
+
+	/**
+	 * Confirms if specific capability is supported
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string $value required ability e.g. 'EntityList'
+	 *
+	 * @return bool
+	 */
+	public function capable(string $value): bool;
+
+	/**
+	 * Lists all supported capabilities
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @return array<string,bool>
+	 */
+	public function capabilities(): array;
+
+	/**
+	 * Unique identifier of the provider this service belongs to
+	 *
+	 * @since 2025.11.01
+	 */
+	public function in(): string;
+
+	/**
+	 * Unique arbitrary text string identifying this service (e.g. 1 or service1 or anything else)
+	 *
+	 * @since 2025.11.01
+	 */
+	public function id(): string|int;
+
+	/**
+	 * Gets the localized human friendly name of this service (e.g. ACME Company File Service)
+	 *
+	 * @since 2025.11.01
+	 */
+	public function getLabel(): string;
+
+	/**
+	 * Gets the active status of this service
+	 *
+	 * @since 2025.11.01
+	 */
+	public function getEnabled(): bool;
+
+	// ==================== Collection Methods ====================
+
+	/**
+	 * List of accessible collections at a specific location
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $location Parent collection identifier, null for root
+	 *
+	 * @return array<string|int,INodeCollectionBase>
+	 */
+	public function collectionList(string|int|null $location = null, ?IFilter $filter = null, ?ISort $sort = null): array;
+
+	/**
+	 * Fresh filter for collection list
+	 *
+	 * @since 2025.11.01
+	 */
+	public function collectionListFilter(): IFilter;
+
+	/**
+	 * Fresh sort for collection list
+	 *
+	 * @since 2025.11.01
+	 */
+	public function collectionListSort(): ISort;
+
+	/**
+	 * Confirms if specific collection exists
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $identifier Collection identifier
+	 */
+	public function collectionExtant(string|int|null $identifier): bool;
+
+	/**
+	 * Fetches details about a specific collection
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $identifier Collection identifier
+	 */
+	public function collectionFetch(string|int|null $identifier): ?INodeCollectionBase;
+
+	// ==================== Entity Methods ====================
+
+	/**
+	 * Lists all entities in a specific collection
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $collection Collection identifier
+	 *
+	 * @return array<string|int,INodeEntityBase>
+	 */
+	public function entityList(string|int|null $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null): array;
+
+	/**
+	 * Fresh filter for entity list
+	 *
+	 * @since 2025.11.01
+	 */
+	public function entityListFilter(): IFilter;
+
+	/**
+	 * Fresh sort for entity list
+	 *
+	 * @since 2025.11.01
+	 */
+	public function entityListSort(): ISort;
+
+	/**
+	 * Fresh range for entity list
+	 *
+	 * @since 2025.11.01
+	 */
+	public function entityListRange(RangeType $type): IRange;
+
+	/**
+	 * Lists all changes from a specific signature
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $collection Collection identifier
+	 * @param string $signature Sync token signature
+	 * @param string $detail Detail level: ids | meta | full
+	 *
+	 * @return array{
+	 *     added: array<string|int>,
+	 *     updated: array<string|int>,
+	 *     deleted: array<string|int>,
+	 *     signature: string
+	 * }
+	 */
+	public function entityDelta(string|int|null $collection, string $signature, string $detail = 'ids'): array;
+
+	/**
+	 * Confirms if specific entities exist in a collection
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $collection Collection identifier
+	 * @param string|int ...$identifiers Entity identifiers
+	 *
+	 * @return array<string|int,bool>
+	 */
+	public function entityExtant(string|int|null $collection, string|int ...$identifiers): array;
+
+	/**
+	 * Fetches details about specific entities in a collection
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $collection Collection identifier
+	 * @param string|int ...$identifiers Entity identifiers
+	 *
+	 * @return array<string|int,INodeEntityBase>
+	 */
+	public function entityFetch(string|int|null $collection, string|int ...$identifiers): array;
+
+	/**
+	 * Reads the entire content of an entity as a string
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $collection Collection identifier
+	 * @param string|int $identifier Entity identifier
+	 *
+	 * @return string|null File content or null if not found
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function entityRead(string|int|null $collection, string|int $identifier): ?string;
+
+	/**
+	 * Opens a stream to read the content of an entity
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $collection Collection identifier
+	 * @param string|int $identifier Entity identifier
+	 *
+	 * @return resource|null Stream resource or null if not found
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function entityReadStream(string|int|null $collection, string|int $identifier);
+
+	/**
+	 * Reads a chunk of content from an entity
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $collection Collection identifier
+	 * @param string|int $identifier Entity identifier
+	 * @param int $offset Starting byte position (0-indexed)
+	 * @param int $length Number of bytes to read
+	 *
+	 * @return string|null Chunk content or null if not found
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function entityReadChunk(string|int|null $collection, string|int $identifier, int $offset, int $length): ?string;
+
+	// ==================== Node Methods (Recursive/Unified) ====================
+
+	/**
+	 * Lists all nodes (collections and entities) at a location, optionally recursive
+	 * Returns a flat list with parent references via in()
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $location Starting location, null for root
+	 * @param bool $recursive Whether to list recursively
+	 *
+	 * @return array<string|int,INodeBase>
+	 */
+	public function nodeList(string|int|null $location = null, bool $recursive = false, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null): array;
+
+	/**
+	 * Fresh filter for node list
+	 *
+	 * @since 2025.11.01
+	 */
+	public function nodeListFilter(): IFilter;
+
+	/**
+	 * Fresh sort for node list
+	 *
+	 * @since 2025.11.01
+	 */
+	public function nodeListSort(): ISort;
+
+	/**
+	 * Fresh range for node list
+	 *
+	 * @since 2025.11.01
+	 */
+	public function nodeListRange(RangeType $type): IRange;
+
+	/**
+	 * Lists all node changes from a specific signature, optionally recursive
+	 * Returns flat list with parent references
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $location Starting location, null for root
+	 * @param string $signature Sync token signature
+	 * @param bool $recursive Whether to include recursive changes
+	 * @param string $detail Detail level: ids | meta | full
+	 *
+	 * @return array{
+	 *     added: array<string|int,INodeBase>|array<string|int>,
+	 *     updated: array<string|int,INodeBase>|array<string|int>,
+	 *     deleted: array<string|int>,
+	 *     signature: string
+	 * }
+	 */
+	public function nodeDelta(string|int|null $location, string $signature, bool $recursive = false, string $detail = 'ids'): array;
+
+}

shared/lib/Files/Service/IServiceCollectionMutable.php

@@ -0,0 +1,100 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Files\Service;
+
+use KTXF\Files\Node\INodeCollectionBase;
+use KTXF\Files\Node\INodeCollectionMutable;
+
+interface IServiceCollectionMutable extends IServiceBase {
+
+	public const CAPABILITY_COLLECTION_CREATE = 'CollectionCreate';
+	public const CAPABILITY_COLLECTION_MODIFY = 'CollectionModify';
+	public const CAPABILITY_COLLECTION_DESTROY = 'CollectionDestroy';
+	public const CAPABILITY_COLLECTION_COPY = 'CollectionCopy';
+	public const CAPABILITY_COLLECTION_MOVE = 'CollectionMove';
+
+	/**
+	 * Creates a new, empty collection node
+	 *
+	 * @since 2025.11.01
+	 */
+	public function collectionFresh(): INodeCollectionMutable;
+
+	/**
+	 * Creates a new collection at the specified location
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $location Parent collection, null for root
+	 * @param INodeCollectionMutable $collection The collection to create
+	 * @param array $options Additional options
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function collectionCreate(string|int|null $location, INodeCollectionMutable $collection, array $options = []): INodeCollectionBase;
+
+	/**
+	 * Modifies an existing collection
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int $identifier Collection identifier
+	 * @param INodeCollectionMutable $collection The collection with modifications
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function collectionModify(string|int $identifier, INodeCollectionMutable $collection): INodeCollectionBase;
+
+	/**
+	 * Destroys an existing collection
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int $identifier Collection identifier
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function collectionDestroy(string|int $identifier): bool;
+
+	/**
+	 * Copies an existing collection to a new location
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int $identifier Collection identifier
+	 * @param string|int|null $location Destination parent collection, null for root
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function collectionCopy(string|int $identifier, string|int|null $location): INodeCollectionBase;
+
+	/**
+	 * Moves an existing collection to a new location
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int $identifier Collection identifier
+	 * @param string|int|null $location Destination parent collection, null for root
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function collectionMove(string|int $identifier, string|int|null $location): INodeCollectionBase;
+
+}

shared/lib/Files/Service/IServiceEntityMutable.php

@@ -0,0 +1,158 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Files\Service;
+
+use KTXF\Files\Node\INodeEntityBase;
+use KTXF\Files\Node\INodeEntityMutable;
+
+interface IServiceEntityMutable extends IServiceBase {
+
+	public const CAPABILITY_ENTITY_CREATE = 'EntityCreate';
+	public const CAPABILITY_ENTITY_MODIFY = 'EntityModify';
+	public const CAPABILITY_ENTITY_DESTROY = 'EntityDestroy';
+	public const CAPABILITY_ENTITY_COPY = 'EntityCopy';
+	public const CAPABILITY_ENTITY_MOVE = 'EntityMove';
+	public const CAPABILITY_ENTITY_WRITE = 'EntityWrite';
+	public const CAPABILITY_ENTITY_WRITE_STREAM = 'EntityWriteStream';
+	public const CAPABILITY_ENTITY_WRITE_CHUNK = 'EntityWriteChunk';
+
+	/**
+	 * Creates a new, empty entity node
+	 *
+	 * @since 2025.11.01
+	 */
+	public function entityFresh(): INodeEntityMutable;
+
+	/**
+	 * Creates a new entity in the specified collection
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $collection Collection identifier, null for root
+	 * @param INodeEntityMutable $entity The entity to create
+	 * @param array $options Additional options
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function entityCreate(string|int|null $collection, INodeEntityMutable $entity, array $options = []): INodeEntityBase;
+
+	/**
+	 * Modifies an existing entity in the specified collection
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $collection Collection identifier
+	 * @param string|int $identifier Entity identifier
+	 * @param INodeEntityMutable $entity The entity with modifications
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function entityModify(string|int|null $collection, string|int $identifier, INodeEntityMutable $entity): INodeEntityBase;
+
+	/**
+	 * Destroys an existing entity in the specified collection
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $collection Collection identifier
+	 * @param string|int $identifier Entity identifier
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function entityDestroy(string|int|null $collection, string|int $identifier): bool;
+
+	/**
+	 * Copies an existing entity to a new collection
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $collection Source collection identifier
+	 * @param string|int $identifier Entity identifier
+	 * @param string|int|null $destination Destination collection identifier, null for root
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function entityCopy(string|int|null $collection, string|int $identifier, string|int|null $destination): INodeEntityBase;
+
+	/**
+	 * Moves an existing entity to a new collection
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $collection Source collection identifier
+	 * @param string|int $identifier Entity identifier
+	 * @param string|int|null $destination Destination collection identifier, null for root
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function entityMove(string|int|null $collection, string|int $identifier, string|int|null $destination): INodeEntityBase;
+
+	/**
+	 * Writes the entire content of an entity from a string
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $collection Collection identifier
+	 * @param string|int $identifier Entity identifier
+	 * @param string $data Content to write
+	 *
+	 * @return int Number of bytes written
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function entityWrite(string|int|null $collection, string|int $identifier, string $data): int;
+
+	/**
+	 * Opens a stream to write the content of an entity
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $collection Collection identifier
+	 * @param string|int $identifier Entity identifier
+	 *
+	 * @return resource Stream resource for writing
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function entityWriteStream(string|int|null $collection, string|int $identifier);
+
+	/**
+	 * Writes a chunk of content to an entity at a specific position
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $collection Collection identifier
+	 * @param string|int $identifier Entity identifier
+	 * @param int $offset Starting byte position (0-indexed)
+	 * @param string $data Chunk content to write
+	 *
+	 * @return int Number of bytes written
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function entityWriteChunk(string|int|null $collection, string|int $identifier, int $offset, string $data): int;
+
+}

shared/lib/Files/Service/IServiceMutable.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\Files\Service;
+
+use KTXF\Json\JsonDeserializable;
+
+interface IServiceMutable extends IServiceBase, JsonDeserializable {
+
+	/**
+	 * Sets the localized human friendly name of this service
+	 *
+	 * @since 2025.11.01
+	 */
+	public function setLabel(string $value): static;
+
+	/**
+	 * Sets the active status of this service
+	 *
+	 * @since 2025.11.01
+	 */
+	public function setEnabled(bool $value): static;
+
+}