feat: import people

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

lib/Import/ImportCountEvent.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXM\PeopleManager\Import;
+
+use KTXM\PeopleManager\Stream\ExpectedTotal;
+
+/**
+ * Carries the total number of vCards discovered in the source.
+ * Yielded once, before any object events, when counting is enabled.
+ *
+ * The stream envelope consumes this as the `control:start` total (the progress
+ * denominator); it is never emitted as a `data` frame, so it carries no payload
+ * of its own.
+ */
+final readonly class ImportCountEvent implements ImportEvent, ExpectedTotal {
+
+    public function __construct(
+        public int $total,
+    ) {}
+
+    public function expectedTotal(): int {
+        return $this->total;
+    }
+
+    /**
+     * @return array{total: int}
+     */
+    public function jsonSerialize(): array {
+        return ['total' => $this->total];
+    }
+}