<?php

declare(strict_types=1);

namespace App\FormBuilder\Purposes\Resolvers;

use App\Exceptions\FormBuilder\PurposeSubjectResolutionException;
use App\FormBuilder\Purposes\PurposeSubjectResolver;
use App\Models\FormBuilder\FormSubmission;
use Illuminate\Database\Eloquent\Model;

/**
 * RFC §3 Q9 — artist_advance: subject is the Artist resolved via the
 * portal token that opened the submission. Throws if no token.
 *
 * The Artist model is not yet implemented (BACKLOG: ARCH-09); this
 * resolver short-circuits when the submission already carries
 * subject_type='artist' (set by the portal route) — the typical path.
 * If subject is absent, throw — the route should never have allowed
 * the submission through without a portal token.
 */
final readonly class ArtistAdvanceSubjectResolver implements PurposeSubjectResolver
{
    public function resolveOrProvision(FormSubmission $submission): Model
    {
        if ($submission->subject_type === 'artist' && $submission->subject_id !== null) {
            $subject = $submission->subject;
            if ($subject !== null) {
                return $subject;
            }
            throw new PurposeSubjectResolutionException(
                'artist_advance',
                'subject_not_found',
                (string) $submission->id,
                "submission claims artist subject {$submission->subject_id} but record is gone",
            );
        }

        throw new PurposeSubjectResolutionException(
            'artist_advance',
            'no_portal_token',
            (string) $submission->id,
            'artist_advance submission has no resolved Artist; portal token missing',
        );
    }
}