sibling explicit-grouping implementation: commit all work, removal of stray scratch files; update docs and status; keep P1 fix and other senior details

src/Indexer/Contracts/ExplicitImportGroupingAdapterInterface.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MeshVault\Indexer\Contracts;
+
+use MeshVault\Indexer\ScannedFile;
+
+/**
+ * Explicit, user-confirmed import grouping with decision persistence for replay/idempotency.
+ * Contrasts with LegacyGuessedImportGroupingAdapter which performs fresh stateless lookups.
+ */
+interface ExplicitImportGroupingAdapterInterface
+{
+    /**
+     * Resolve or create a model for the given file under explicit user confirmation.
+     *
+     * @param string $sourcePath Absolute source root
+     * @param ScannedFile $file File with relativePath, size, hash
+     * @param array<string, mixed> $context Optional confirmation context:
+     *     - 'model_id' => int: user-selected existing model (must match folder/title)
+     *     - 'model_name' => string: user-provided model title
+     *     - 'folder_path' => string: user-provided folder path (must exist or be creatable)
+     *     - 'create_new' => bool: force new model even if match exists
+     * @return int Model ID (existing or newly created)
+     * @throws \DomainException If context conflicts with existing catalog state
+     * @throws \InvalidArgumentException If context is malformed
+     */
+    public function modelFor(string $sourcePath, ScannedFile $file, array $context = []): int;
+
+    /**
+     * Persist the user's grouping decision for replay/idempotency.
+     * Called after successful import job creation with confirmed context.
+     *
+     * @param int $jobId Import job ID
+     * @param list<array{source_path: string, model_id: int, context: array}> $decisions
+     * @return void
+     */
+    public function persistDecisions(int $jobId, array $decisions): void;
+
+    /**
+     * Recover grouping decisions for a resumed/interrupted job.
+     * Returns model_id per source_path, or empty array if no decision was recorded.
+     *
+     * @param int $jobId Import job ID
+     * @return array<string, int> Map of source_path => model_id
+     */
+    public function recoverDecisions(int $jobId): array;
+}