TenantAtlas/apps/platform/app/Support/OpsUx/OperationUxPresenter.php

<?php

declare(strict_types=1);

namespace App\Support\OpsUx;

use App\Filament\Resources\FindingResource;
use App\Models\AlertRule;
use App\Models\Finding;
use App\Models\OperationRun;
use App\Models\PlatformUser;
use App\Models\Tenant;
use App\Support\OperationCatalog;
use App\Support\OperationRunLinks;
use App\Support\Operations\OperationRunFreshnessState;
use App\Support\ReasonTranslation\ReasonPresenter;
use App\Support\ReasonTranslation\ReasonResolutionEnvelope;
use App\Support\RedactionIntegrity;
use App\Support\System\SystemOperationRunLinks;
use App\Support\Ui\DerivedState\DerivedStateFamily;
use App\Support\Ui\DerivedState\DerivedStateKey;
use App\Support\Ui\DerivedState\RequestScopedDerivedStateStore;
use App\Support\Ui\GovernanceArtifactTruth\ArtifactTruthPresenter;
use App\Support\Ui\OperatorExplanation\OperatorExplanationPattern;
use Filament\Actions\Action;
use Filament\Notifications\Notification as FilamentNotification;

final class OperationUxPresenter
{
    public const int QUEUED_TOAST_DURATION_MS = 4000;

    public const int FAILURE_MESSAGE_MAX_CHARS = 140;

    /**
     * Queued intent feedback toast (ephemeral, not persisted).
     */
    public static function queuedToast(string $operationType): FilamentNotification
    {
        $operationLabel = OperationCatalog::label($operationType);

        return FilamentNotification::make()
            ->title("{$operationLabel} queued")
            ->body('Queued for execution. Open the operation for progress and next steps.')
            ->info()
            ->duration(self::QUEUED_TOAST_DURATION_MS);
    }

    /**
     * Canonical dedupe feedback when a matching run is already active.
     */
    public static function alreadyQueuedToast(string $operationType): FilamentNotification
    {
        $operationLabel = OperationCatalog::label($operationType);

        return FilamentNotification::make()
            ->title("{$operationLabel} already queued")
            ->body('A matching operation is already queued or running. No action needed unless it stays stuck.')
            ->info()
            ->duration(self::QUEUED_TOAST_DURATION_MS);
    }

    /**
     * Canonical provider-backed dedupe feedback using the shared start vocabulary.
     */
    public static function alreadyRunningToast(string $operationType): FilamentNotification
    {
        $operationLabel = OperationCatalog::label($operationType);

        return FilamentNotification::make()
            ->title("{$operationLabel} already running")
            ->body('A matching operation is already queued or running. Open the operation for progress and next steps.')
            ->info()
            ->duration(self::QUEUED_TOAST_DURATION_MS);
    }

    /**
     * Canonical provider-backed protected-scope conflict feedback.
     */
    public static function scopeBusyToast(
        string $title = 'Scope busy',
        string $body = 'Another provider-backed operation is already running for this scope. Open the active operation for progress and next steps.',
    ): FilamentNotification {
        return FilamentNotification::make()
            ->title($title)
            ->body($body)
            ->warning()
            ->duration(self::QUEUED_TOAST_DURATION_MS);
    }

    /**
     * @param  array<string, mixed>  $event
     * @return array<string, mixed>
     */
    public static function findingDatabaseNotificationMessage(Finding $finding, Tenant $tenant, array $event): array
    {
        return self::databaseNotificationMessage(
            title: self::findingNotificationTitle($event),
            body: self::findingNotificationBody($event),
            status: self::findingNotificationStatus($event),
            actionName: 'open_finding',
            actionLabel: 'Open finding',
            actionUrl: FindingResource::getUrl(
                'view',
                ['record' => $finding],
                panel: 'tenant',
                tenant: $tenant,
            ),
            actionTarget: 'finding_detail',
            supportingLines: self::findingNotificationSupportingLines($event),
        );
    }

    /**
     * @return array<string, mixed>
     */
    public static function queuedDatabaseNotificationMessage(OperationRun $run, object $notifiable): array
    {
        $operationLabel = OperationCatalog::label((string) $run->type);
        $primaryAction = self::operationRunPrimaryAction($run, $notifiable);

        return self::databaseNotificationMessage(
            title: "{$operationLabel} queued",
            body: 'Queued for execution. Open the operation for progress and next steps.',
            status: 'info',
            actionName: 'view_run',
            actionLabel: $primaryAction['label'],
            actionUrl: $primaryAction['url'],
            actionTarget: $primaryAction['target'],
        );
    }

    /**
     * Terminal DB notification payload.
     *
     * Note: We intentionally return the built Filament notification builder to
     * keep DB formatting consistent with existing Notification classes.
     */
    public static function terminalDatabaseNotification(OperationRun $run, ?Tenant $tenant = null): FilamentNotification
    {
        $payload = self::terminalNotificationPayload($run);
        $actionUrl = $tenant instanceof Tenant
            ? OperationRunUrl::view($run, $tenant)
            : OperationRunLinks::tenantlessView($run);

        return self::makeDatabaseNotification(
            title: $payload['title'],
            body: $payload['body'],
            status: $payload['status'],
            actionName: 'view_run',
            actionLabel: OperationRunLinks::openLabel(),
            actionUrl: $actionUrl,
            supportingLines: $payload['supportingLines'],
        );
    }

    /**
     * @return array<string, mixed>
     */
    public static function terminalDatabaseNotificationMessage(OperationRun $run, object $notifiable): array
    {
        $payload = self::terminalNotificationPayload($run);
        $primaryAction = self::operationRunPrimaryAction($run, $notifiable);

        return self::databaseNotificationMessage(
            title: $payload['title'],
            body: $payload['body'],
            status: $payload['status'],
            actionName: 'view_run',
            actionLabel: $primaryAction['label'],
            actionUrl: $primaryAction['url'],
            actionTarget: $primaryAction['target'],
            supportingLines: $payload['supportingLines'],
        );
    }

    public static function surfaceGuidance(OperationRun $run): ?string
    {
        return self::memoizeGuidance(
            run: $run,
            variant: 'surface_guidance',
            resolver: fn (): ?string => self::buildSurfaceGuidance($run),
        );
    }

    public static function surfaceGuidanceFresh(OperationRun $run): ?string
    {
        return self::memoizeGuidance(
            run: $run,
            variant: 'surface_guidance',
            resolver: fn (): ?string => self::buildSurfaceGuidance($run),
            fresh: true,
        );
    }

    private static function buildSurfaceGuidance(OperationRun $run): ?string
    {
        $uxStatus = OperationStatusNormalizer::toUxStatus($run->status, $run->outcome);
        $reasonEnvelope = self::reasonEnvelope($run);
        $reasonGuidance = app(ReasonPresenter::class)->guidance($reasonEnvelope);
        $operatorExplanationGuidance = self::operatorExplanationGuidance($run);
        $nextStepLabel = self::firstNextStepLabel($run);
        $freshnessState = self::freshnessState($run);

        if ($freshnessState->isLikelyStale()) {
            return 'This operation is past its lifecycle window. Review worker health and logs before retrying from the start surface.';
        }

        if ($freshnessState->isReconciledFailed()) {
            return $operatorExplanationGuidance
                ?? $reasonGuidance
                ?? 'TenantPilot reconciled this operation after lifecycle truth was lost. Review the recorded evidence before retrying.';
        }

        if (in_array($uxStatus, ['blocked', 'failed', 'partial'], true)) {
            if ($operatorExplanationGuidance !== null) {
                return $operatorExplanationGuidance;
            }

            if ($reasonGuidance !== null) {
                return $reasonGuidance;
            }
        }

        if ($uxStatus === 'succeeded' && $operatorExplanationGuidance !== null) {
            return $operatorExplanationGuidance;
        }

        return match ($uxStatus) {
            'queued' => 'No action needed yet. The operation is waiting for a worker.',
            'running' => 'No action needed yet. The operation is currently in progress.',
            'succeeded' => 'No action needed.',
            'partial' => $nextStepLabel !== null
                ? 'Next step: '.$nextStepLabel.'.'
                : (self::requiresFollowUp($run)
                    ? 'Review the affected items before rerunning.'
                    : 'No action needed unless the recorded warnings were unexpected.'),
            'blocked' => $nextStepLabel !== null
                ? 'Next step: '.$nextStepLabel.'.'
                : 'Review the blocked prerequisite before retrying.',
            default => $nextStepLabel !== null
                ? 'Next step: '.$nextStepLabel.'.'
                : 'Review the operation details before retrying.',
        };
    }

    public static function surfaceFailureDetail(OperationRun $run): ?string
    {
        return self::memoizeExplanation(
            run: $run,
            variant: 'surface_failure_detail',
            resolver: fn (): ?string => self::buildSurfaceFailureDetail($run),
        );
    }

    public static function surfaceFailureDetailFresh(OperationRun $run): ?string
    {
        return self::memoizeExplanation(
            run: $run,
            variant: 'surface_failure_detail',
            resolver: fn (): ?string => self::buildSurfaceFailureDetail($run),
            fresh: true,
        );
    }

    private static function buildSurfaceFailureDetail(OperationRun $run): ?string
    {
        $operatorExplanation = self::governanceOperatorExplanation($run);

        if (is_string($operatorExplanation?->dominantCauseExplanation) && trim($operatorExplanation->dominantCauseExplanation) !== '') {
            return trim($operatorExplanation->dominantCauseExplanation);
        }

        $failureMessage = (string) (($run->failure_summary[0]['message'] ?? '') ?? '');
        $sanitizedFailureMessage = self::sanitizeFailureMessage($failureMessage);

        if ($sanitizedFailureMessage !== null) {
            return $sanitizedFailureMessage;
        }

        $reasonEnvelope = self::reasonEnvelope($run);

        if ($reasonEnvelope !== null) {
            return $reasonEnvelope->shortExplanation;
        }

        if (self::freshnessState($run)->isLikelyStale()) {
            return 'This operation is no longer within its normal lifecycle window and may no longer be progressing.';
        }

        return null;
    }

    public static function freshnessState(OperationRun $run): OperationRunFreshnessState
    {
        return $run->freshnessState();
    }

    public static function problemClass(OperationRun $run): string
    {
        return $run->problemClass();
    }

    public static function problemClassLabel(OperationRun $run): ?string
    {
        return match (self::problemClass($run)) {
            OperationRun::PROBLEM_CLASS_ACTIVE_STALE_ATTENTION => 'Likely stale active run',
            OperationRun::PROBLEM_CLASS_TERMINAL_FOLLOW_UP => 'Terminal follow-up',
            default => null,
        };
    }

    public static function staleLineageNote(OperationRun $run): ?string
    {
        if (! $run->hasStaleLineage()) {
            return null;
        }

        return 'This terminal run was automatically reconciled after stale lifecycle truth was lost.';
    }

    /**
     * @return array{
     *     freshnessState:string,
     *     freshnessLabel:?string,
     *     problemClass:string,
     *     problemClassLabel:?string,
     *     isCurrentlyActive:bool,
     *     isReconciled:bool,
     *     staleLineageNote:?string,
     *     primaryNextAction:string,
     *     attentionNote:?string
     * }
     */
    public static function decisionZoneTruth(OperationRun $run): array
    {
        $freshnessState = self::freshnessState($run);

        return [
            'freshnessState' => $freshnessState->value,
            'freshnessLabel' => self::lifecycleAttentionSummary($run),
            'problemClass' => self::problemClass($run),
            'problemClassLabel' => self::problemClassLabel($run),
            'isCurrentlyActive' => $run->isCurrentlyActive(),
            'isReconciled' => $run->isLifecycleReconciled(),
            'staleLineageNote' => self::staleLineageNote($run),
            'primaryNextAction' => self::surfaceGuidance($run) ?? 'No action needed.',
            'attentionNote' => self::decisionAttentionNote($run),
        ];
    }

    public static function decisionAttentionNote(OperationRun $run): ?string
    {
        return match (self::problemClass($run)) {
            OperationRun::PROBLEM_CLASS_ACTIVE_STALE_ATTENTION => 'Still active: Yes. Automatic reconciliation: No. This run is past its lifecycle window and needs stale-run investigation before retrying.',
            OperationRun::PROBLEM_CLASS_TERMINAL_FOLLOW_UP => $run->hasStaleLineage()
                ? 'Still active: No. Automatic reconciliation: Yes. This terminal failure preserves stale-run lineage so operators can recover why the run stopped.'
                : 'Still active: No. Automatic reconciliation: No. This run is terminal and still needs follow-up.',
            default => null,
        };
    }

    public static function lifecycleAttentionSummary(OperationRun $run): ?string
    {
        return self::memoizeExplanation(
            run: $run,
            variant: 'lifecycle_attention_summary',
            resolver: fn (): ?string => self::buildLifecycleAttentionSummary($run),
        );
    }

    public static function lifecycleAttentionSummaryFresh(OperationRun $run): ?string
    {
        return self::memoizeExplanation(
            run: $run,
            variant: 'lifecycle_attention_summary',
            resolver: fn (): ?string => self::buildLifecycleAttentionSummary($run),
            fresh: true,
        );
    }

    private static function buildLifecycleAttentionSummary(OperationRun $run): ?string
    {
        return match (self::freshnessState($run)) {
            OperationRunFreshnessState::LikelyStale => 'Likely stale',
            OperationRunFreshnessState::ReconciledFailed => 'Automatically reconciled',
            default => self::problemClass($run) === OperationRun::PROBLEM_CLASS_TERMINAL_FOLLOW_UP
                ? 'Terminal follow-up'
                : null,
        };
    }

    /**
     * @param  array<string, mixed>  $event
     * @return list<string>
     */
    private static function findingNotificationSupportingLines(array $event): array
    {
        $recipientReason = self::findingRecipientReasonCopy((string) data_get($event, 'metadata.recipient_reason', ''));

        return $recipientReason !== '' ? [$recipientReason] : [];
    }

    /**
     * @param  array<string, mixed>  $event
     */
    private static function findingNotificationTitle(array $event): string
    {
        $title = trim((string) ($event['title'] ?? 'Finding update'));

        return $title !== '' ? $title : 'Finding update';
    }

    /**
     * @param  array<string, mixed>  $event
     */
    private static function findingNotificationBody(array $event): string
    {
        $body = trim((string) ($event['body'] ?? 'A finding needs follow-up.'));

        return $body !== '' ? $body : 'A finding needs follow-up.';
    }

    /**
     * @param  array<string, mixed>  $event
     */
    private static function findingNotificationStatus(array $event): string
    {
        return match ((string) ($event['event_type'] ?? '')) {
            AlertRule::EVENT_FINDINGS_DUE_SOON => 'warning',
            AlertRule::EVENT_FINDINGS_OVERDUE => 'danger',
            default => 'info',
        };
    }

    private static function findingRecipientReasonCopy(string $reason): string
    {
        return match ($reason) {
            'new_assignee' => 'You are the new assignee.',
            'current_assignee' => 'You are the current assignee.',
            'current_owner' => 'You are the accountable owner.',
            default => '',
        };
    }

    public static function governanceOperatorExplanation(OperationRun $run): ?OperatorExplanationPattern
    {
        return self::resolveGovernanceOperatorExplanation($run);
    }

    public static function governanceDiagnosticSummary(OperationRun $run): ?GovernanceRunDiagnosticSummary
    {
        return self::resolveGovernanceDiagnosticSummary($run);
    }

    public static function governanceDiagnosticSummaryFresh(OperationRun $run): ?GovernanceRunDiagnosticSummary
    {
        return self::resolveGovernanceDiagnosticSummary($run, fresh: true);
    }

    public static function governanceOperatorExplanationFresh(OperationRun $run): ?OperatorExplanationPattern
    {
        return self::resolveGovernanceOperatorExplanation($run, fresh: true);
    }

    /**
     * @return array{titleSuffix: string, body: string, status: string}
     */
    private static function terminalPresentation(OperationRun $run): array
    {
        $uxStatus = OperationStatusNormalizer::toUxStatus($run->status, $run->outcome);
        $reasonEnvelope = self::reasonEnvelope($run);
        $freshnessState = self::freshnessState($run);

        if ($freshnessState->isReconciledFailed()) {
            return [
                'titleSuffix' => 'was automatically reconciled',
                'body' => 'Automatically reconciled after infrastructure failure.',
                'status' => 'danger',
            ];
        }

        return match ($uxStatus) {
            'succeeded' => [
                'titleSuffix' => 'completed successfully',
                'body' => 'Completed successfully.',
                'status' => 'success',
            ],
            'partial' => [
                'titleSuffix' => self::requiresFollowUp($run) ? 'needs follow-up' : 'completed with review notes',
                'body' => 'Completed with follow-up.',
                'status' => 'warning',
            ],
            'blocked' => [
                'titleSuffix' => 'blocked by prerequisite',
                'body' => 'Blocked by prerequisite.',
                'status' => 'warning',
            ],
            default => [
                'titleSuffix' => 'execution failed',
                'body' => 'Execution failed.',
                'status' => 'danger',
            ],
        };
    }

    /**
     * @return array{
     *     title:string,
     *     body:string,
     *     status:string,
     *     supportingLines:list<string>
     * }
     */
    private static function terminalNotificationPayload(OperationRun $run): array
    {
        $operationLabel = OperationCatalog::label((string) $run->type);
        $presentation = self::terminalPresentation($run);

        return [
            'title' => "{$operationLabel} {$presentation['titleSuffix']}",
            'body' => $presentation['body'],
            'status' => $presentation['status'],
            'supportingLines' => self::terminalSupportingLines($run),
        ];
    }

    /**
     * @return list<string>
     */
    private static function terminalSupportingLines(OperationRun $run): array
    {
        $lines = [];
        $reasonLabel = trim((string) (self::reasonEnvelope($run)?->operatorLabel ?? ''));

        if ($reasonLabel !== '') {
            $lines[] = $reasonLabel;
        }

        $failureMessage = self::surfaceFailureDetail($run);

        if ($failureMessage !== null) {
            $lines[] = $failureMessage;
        }

        $guidance = self::surfaceGuidance($run);
        if ($guidance !== null) {
            $lines[] = $guidance;
        }

        $summary = SummaryCountsNormalizer::renderSummaryLine(is_array($run->summary_counts) ? $run->summary_counts : []);
        if ($summary !== null) {
            $lines[] = $summary;
        }

        $integritySummary = RedactionIntegrity::noteForRun($run);
        if (is_string($integritySummary) && trim($integritySummary) !== '') {
            $lines[] = trim($integritySummary);
        }

        return array_values(array_filter($lines, static fn (string $line): bool => trim($line) !== ''));
    }

    /**
     * @return array{label:string, url:?string, target:string}
     */
    private static function operationRunPrimaryAction(OperationRun $run, object $notifiable): array
    {
        if ($notifiable instanceof PlatformUser) {
            return [
                'label' => OperationRunLinks::openLabel(),
                'url' => SystemOperationRunLinks::view($run),
                'target' => 'system_operation_run',
            ];
        }

        if (self::isManagedTenantOnboardingWizardRun($run)) {
            return [
                'label' => OperationRunLinks::openLabel(),
                'url' => OperationRunLinks::tenantlessView($run),
                'target' => 'tenantless_operation_run',
            ];
        }

        if ($run->tenant instanceof Tenant) {
            return [
                'label' => OperationRunLinks::openLabel(),
                'url' => OperationRunLinks::view($run, $run->tenant),
                'target' => 'admin_operation_run',
            ];
        }

        return [
            'label' => OperationRunLinks::openLabel(),
            'url' => OperationRunLinks::tenantlessView($run),
            'target' => 'tenantless_operation_run',
        ];
    }

    private static function isManagedTenantOnboardingWizardRun(OperationRun $run): bool
    {
        $context = is_array($run->context) ? $run->context : [];
        $wizard = $context['wizard'] ?? null;

        return is_array($wizard)
            && ($wizard['flow'] ?? null) === 'managed_tenant_onboarding';
    }

    /**
     * @param  list<string>  $supportingLines
     */
    private static function makeDatabaseNotification(
        string $title,
        string $body,
        string $status,
        string $actionName,
        string $actionLabel,
        ?string $actionUrl,
        array $supportingLines = [],
    ): FilamentNotification {
        return FilamentNotification::make()
            ->title($title)
            ->body(self::composeDatabaseNotificationBody($body, $supportingLines))
            ->status($status)
            ->actions([
                Action::make($actionName)
                    ->label($actionLabel)
                    ->url($actionUrl),
            ]);
    }

    /**
     * @param  list<string>  $supportingLines
     * @return array<string, mixed>
     */
    private static function databaseNotificationMessage(
        string $title,
        string $body,
        string $status,
        string $actionName,
        string $actionLabel,
        ?string $actionUrl,
        string $actionTarget,
        array $supportingLines = [],
    ): array {
        $message = self::makeDatabaseNotification(
            title: $title,
            body: $body,
            status: $status,
            actionName: $actionName,
            actionLabel: $actionLabel,
            actionUrl: $actionUrl,
            supportingLines: $supportingLines,
        )->getDatabaseMessage();

        $message['supporting_lines'] = array_values(array_filter(
            $supportingLines,
            static fn (string $line): bool => trim($line) !== '',
        ));

        if (is_array($message['actions'][0] ?? null)) {
            $message['actions'][0]['target'] = $actionTarget;
        }

        return $message;
    }

    /**
     * @param  list<string>  $supportingLines
     */
    private static function composeDatabaseNotificationBody(string $body, array $supportingLines): string
    {
        $lines = [trim($body)];

        foreach ($supportingLines as $line) {
            $line = trim($line);

            if ($line === '') {
                continue;
            }

            $lines[] = $line;
        }

        return implode("\n", array_filter($lines, static fn (string $line): bool => $line !== ''));
    }

    private static function requiresFollowUp(OperationRun $run): bool
    {
        if (self::firstNextStepLabel($run) !== null) {
            return true;
        }

        $counts = SummaryCountsNormalizer::normalize(is_array($run->summary_counts) ? $run->summary_counts : []);

        return (int) ($counts['failed'] ?? 0) > 0;
    }

    private static function firstNextStepLabel(OperationRun $run): ?string
    {
        $context = is_array($run->context) ? $run->context : [];
        $nextSteps = $context['next_steps'] ?? null;

        if (! is_array($nextSteps)) {
            return null;
        }

        foreach ($nextSteps as $nextStep) {
            if (! is_array($nextStep)) {
                continue;
            }

            $label = trim((string) ($nextStep['label'] ?? ''));

            if ($label !== '') {
                return $label;
            }
        }

        return null;
    }

    private static function sanitizeFailureMessage(string $failureMessage): ?string
    {
        $failureMessage = trim($failureMessage);

        if ($failureMessage === '') {
            return null;
        }

        $failureMessage = RunFailureSanitizer::sanitizeMessage($failureMessage);

        if (mb_strlen($failureMessage) > self::FAILURE_MESSAGE_MAX_CHARS) {
            $failureMessage = mb_substr($failureMessage, 0, self::FAILURE_MESSAGE_MAX_CHARS - 1).'…';
        }

        return $failureMessage !== '' ? $failureMessage : null;
    }

    private static function reasonEnvelope(OperationRun $run): ?ReasonResolutionEnvelope
    {
        return self::memoizeExplanation(
            run: $run,
            variant: 'reason_envelope_notification',
            resolver: fn (): ?ReasonResolutionEnvelope => app(ReasonPresenter::class)->forOperationRun($run, 'notification'),
        );
    }

    private static function operatorExplanationGuidance(OperationRun $run): ?string
    {
        $operatorExplanation = self::resolveGovernanceOperatorExplanation($run);

        if (! is_string($operatorExplanation?->nextActionText) || trim($operatorExplanation->nextActionText) === '') {
            return null;
        }

        $text = trim($operatorExplanation->nextActionText);

        if (str_ends_with($text, '.')) {
            return $text;
        }

        return $text === 'No action needed'
            ? 'No action needed.'
            : 'Next step: '.$text.'.';
    }

    private static function resolveGovernanceOperatorExplanation(OperationRun $run, bool $fresh = false): ?OperatorExplanationPattern
    {
        if (! $run->supportsOperatorExplanation()) {
            return null;
        }

        return self::memoizeExplanation(
            run: $run,
            variant: 'governance_operator_explanation',
            resolver: fn (): ?OperatorExplanationPattern => $fresh
                ? app(ArtifactTruthPresenter::class)->forOperationRunFresh($run)?->operatorExplanation
                : app(ArtifactTruthPresenter::class)->forOperationRun($run)?->operatorExplanation,
            fresh: $fresh,
        );
    }

    private static function resolveGovernanceDiagnosticSummary(OperationRun $run, bool $fresh = false): ?GovernanceRunDiagnosticSummary
    {
        if (! $run->supportsOperatorExplanation()) {
            return null;
        }

        return self::memoizeExplanation(
            run: $run,
            variant: 'governance_diagnostic_summary',
            resolver: fn (): ?GovernanceRunDiagnosticSummary => app(GovernanceRunDiagnosticSummaryBuilder::class)->build(
                run: $run,
                artifactTruth: $fresh
                    ? app(ArtifactTruthPresenter::class)->forOperationRunFresh($run)
                    : app(ArtifactTruthPresenter::class)->forOperationRun($run),
                operatorExplanation: $fresh
                    ? self::resolveGovernanceOperatorExplanation($run, fresh: true)
                    : self::resolveGovernanceOperatorExplanation($run),
                reasonEnvelope: app(ReasonPresenter::class)->forOperationRun($run, 'run_detail'),
            ),
            fresh: $fresh,
        );
    }

    private static function memoizeGuidance(
        OperationRun $run,
        string $variant,
        callable $resolver,
        bool $fresh = false,
    ): ?string {
        $key = DerivedStateKey::fromModel(DerivedStateFamily::OperationUxGuidance, $run, $variant);

        /** @var ?string $value */
        $value = $fresh
            ? self::derivedStateStore()->resolveFresh(
                $key,
                $resolver,
                DerivedStateFamily::OperationUxGuidance->defaultFreshnessPolicy(),
                DerivedStateFamily::OperationUxGuidance->allowsNegativeResultCache(),
            )
            : self::derivedStateStore()->resolve(
                $key,
                $resolver,
                DerivedStateFamily::OperationUxGuidance->defaultFreshnessPolicy(),
                DerivedStateFamily::OperationUxGuidance->allowsNegativeResultCache(),
            );

        return $value;
    }

    private static function memoizeExplanation(
        OperationRun $run,
        string $variant,
        callable $resolver,
        bool $fresh = false,
    ): mixed {
        $key = DerivedStateKey::fromModel(DerivedStateFamily::OperationUxExplanation, $run, $variant);

        return $fresh
            ? self::derivedStateStore()->resolveFresh(
                $key,
                $resolver,
                DerivedStateFamily::OperationUxExplanation->defaultFreshnessPolicy(),
                DerivedStateFamily::OperationUxExplanation->allowsNegativeResultCache(),
            )
            : self::derivedStateStore()->resolve(
                $key,
                $resolver,
                DerivedStateFamily::OperationUxExplanation->defaultFreshnessPolicy(),
                DerivedStateFamily::OperationUxExplanation->allowsNegativeResultCache(),
            );
    }

    private static function derivedStateStore(): RequestScopedDerivedStateStore
    {
        return app(RequestScopedDerivedStateStore::class);
    }
}