Phase 6 Domain layer: constructor invariants, FieldValueBag, domain events #6

Phase 6 — domain models grow real semantics.

Invariants on Category, Field, Item:
- Non-null ids must be >= 1; categoryId must be >= 1.
- Names and slugs cannot be empty (whitespace-trimmed).
- Position and timestamps cannot be negative.
- Violations raise \InvalidArgumentException — caller programming error,
  not a runtime/user-input concern (those are still routed through
  ValidationException at the storage / Sanitizer boundary).

FieldValueBag:
- Replaces Item->data's bare array<string, mixed> with an immutable
  typed wrapper.
- Provides has / get / with / without / merge / toArray / isEmpty /
  count, with `with`/`without`/`merge` returning a new instance every
  time.
- Distinguishes "key absent" from "value is null" so a Field plugin can
  legitimately store null values without confusing default-resolution.
- Item's constructor still accepts FieldValueBag|array for ergonomic
  test setups; the property type is always FieldValueBag.

Domain events:
- DomainEvent marker interface + nine concrete events
  (Category/Field/Item × Created/Updated/Deleted) as final readonly
  data records. No dispatcher yet — that lands together with Scriptor's
  hook system in a later phase.
- Updated events carry both `previous` and `current` so listeners can
  diff. Deleted events carry enough context (ids, name) to react
  without re-fetching the now-missing record.

Storage adapters updated:
- InMemoryStorage::fieldValue() and SqliteItemRepository's
  encode/hydrate paths read/write through FieldValueBag::toArray().
- Phase 5's Query layer keeps working because the structural-vs-JSON
  switch already routed dynamic field reads through a single helper.

Tests: 266 / 567 assertions; PHPStan 8 + Psalm 3 clean.

(Per discussion: typed *Id value objects intentionally NOT introduced
in this phase — three aggregates make the boilerplate cost outweigh
the type-safety benefit. We can adopt them surgically later if a hot
spot calls for it.)

Author: bigin

docs/imanager-2.0-plan.md

@@ -273,8 +273,8 @@ können parallel laufen, sobald ihre Vorbedingungen erfüllt sind.
 | 2 | Architektur-Foundations | ✅ done | `phase-2-foundations` (PR #1, squashed → main) |
 | 3 | Storage-Abstraktion | ✅ done | `phase-3-storage-iface` (PR #2, squashed → main) |
 | 4 | SQLite-Implementierung | ✅ done | `phase-4-sqlite` (PR #4, squashed → main) |
-| 5 | Query-Builder & Selector-DSL | 🟡 in progress | `phase-5-query` |
-| 6 | Domain-Models neu | ⬜ todo | `phase-6-domain` |
+| 5 | Query-Builder & Selector-DSL | ✅ done | `phase-5-query` (PR #5, squashed → main) |
+| 6 | Domain-Models neu | 🟡 in progress | `phase-6-domain` |
 | 7 | Field-Type-System | ⬜ todo | `phase-7-fields` |
 | 8 | Volltextsuche (FTS5) | ⬜ todo | `phase-8-fts` |
 | 9 | Migration-Tool (1.x → 2.0) | ⬜ todo | `phase-9-migration` |

src/Domain/Category.php

@@ -5,11 +5,12 @@
 namespace Imanager\Domain;
 
 /**
- * Anemic data carrier for a category.
+ * A content category — the top-level grouping that owns fields and items.
  *
- * Phase 3 keeps this intentionally lightweight; Phase 6 will enrich it with
- * domain-level invariants, factory methods, and `CategoryId` value-object
- * wrappers (if we decide to introduce them).
+ * `Category` is a value object. Constructor invariants enforce structural
+ * sanity (non-empty name and slug, non-negative position, monotonically
+ * non-negative timestamps); business rules like uniqueness or slug format
+ * live at the storage / Sanitizer boundary, not here.
  */
 final readonly class Category
 {
@@ -20,7 +21,23 @@ public function __construct(
         public int $position = 0,
         public int $created = 0,
         public int $updated = 0,
-    ) {}
+    ) {
+        if ($id !== null && $id < 1) {
+            throw new \InvalidArgumentException('Category id, when set, must be >= 1');
+        }
+        if (trim($name) === '') {
+            throw new \InvalidArgumentException('Category name must not be empty');
+        }
+        if (trim($slug) === '') {
+            throw new \InvalidArgumentException('Category slug must not be empty');
+        }
+        if ($position < 0) {
+            throw new \InvalidArgumentException('Category position must be >= 0');
+        }
+        if ($created < 0 || $updated < 0) {
+            throw new \InvalidArgumentException('Category timestamps must be >= 0');
+        }
+    }
 
     public function withId(int $id): self
     {

src/Domain/Event/CategoryCreated.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Imanager\Domain\Event;
+
+use Imanager\Domain\Category;
+
+final readonly class CategoryCreated implements DomainEvent
+{
+    public function __construct(
+        public Category $category,
+        public int $occurredAt,
+    ) {}
+
+    public function occurredAt(): int
+    {
+        return $this->occurredAt;
+    }
+}

src/Domain/Event/CategoryDeleted.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Imanager\Domain\Event;
+
+final readonly class CategoryDeleted implements DomainEvent
+{
+    public function __construct(
+        public int $categoryId,
+        public int $occurredAt,
+    ) {}
+
+    public function occurredAt(): int
+    {
+        return $this->occurredAt;
+    }
+}

src/Domain/Event/CategoryUpdated.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Imanager\Domain\Event;
+
+use Imanager\Domain\Category;
+
+final readonly class CategoryUpdated implements DomainEvent
+{
+    public function __construct(
+        public Category $previous,
+        public Category $current,
+        public int $occurredAt,
+    ) {}
+
+    public function occurredAt(): int
+    {
+        return $this->occurredAt;
+    }
+}

src/Domain/Event/DomainEvent.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Imanager\Domain\Event;
+
+/**
+ * Marker interface for every domain event raised by the iManager core.
+ *
+ * Phase 6 ships only the data classes — they're pure records carrying the
+ * state changes that storage operations produced. A dispatcher and listener
+ * registry land alongside Scriptor's hook system in a later phase; this
+ * interface plus the concrete events are everything that needs to exist
+ * in iManager itself.
+ */
+interface DomainEvent
+{
+    /**
+     * Unix timestamp (seconds) at which the event happened.
+     */
+    public function occurredAt(): int;
+}

src/Domain/Event/FieldCreated.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Imanager\Domain\Event;
+
+use Imanager\Domain\Field;
+
+final readonly class FieldCreated implements DomainEvent
+{
+    public function __construct(
+        public Field $field,
+        public int $occurredAt,
+    ) {}
+
+    public function occurredAt(): int
+    {
+        return $this->occurredAt;
+    }
+}

src/Domain/Event/FieldDeleted.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Imanager\Domain\Event;
+
+final readonly class FieldDeleted implements DomainEvent
+{
+    public function __construct(
+        public int $fieldId,
+        public int $categoryId,
+        public string $name,
+        public int $occurredAt,
+    ) {}
+
+    public function occurredAt(): int
+    {
+        return $this->occurredAt;
+    }
+}

src/Domain/Event/FieldUpdated.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Imanager\Domain\Event;
+
+use Imanager\Domain\Field;
+
+final readonly class FieldUpdated implements DomainEvent
+{
+    public function __construct(
+        public Field $previous,
+        public Field $current,
+        public int $occurredAt,
+    ) {}
+
+    public function occurredAt(): int
+    {
+        return $this->occurredAt;
+    }
+}

src/Domain/Event/ItemCreated.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Imanager\Domain\Event;
+
+use Imanager\Domain\Item;
+
+final readonly class ItemCreated implements DomainEvent
+{
+    public function __construct(
+        public Item $item,
+        public int $occurredAt,
+    ) {}
+
+    public function occurredAt(): int
+    {
+        return $this->occurredAt;
+    }
+}