<?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;
}