<?php
/**
 * The record of every change a write tool made.
 *
 * @package MazeAi
 * @since   0.1.0
 */

declare(strict_types=1);

namespace MazeAi\Tools;

defined('ABSPATH') || exit;

use MazeAi\Kernel\Support\ToolContext;

/**
 * Write tools (decision 037) are the plugin's own abilities with an undo handler. While the registry runs one, the
 * journal holds the call's `ToolContext`; the ability records what it changed (before and after) under the call's
 * idempotency key, and refuses to run when no context is open, so nothing but an approved chat call can use it.
 *
 * A retried step finds the change already recorded under its key and is handed the recorded outcome instead of
 * writing twice. Undo runs the tool's handler and marks the change undone, once.
 *
 * @since 0.1.0
 */
abstract class ChangeJournal
{
    /** @var array<string, array{preview: callable(array<string, mixed>): string, undo: callable(array<string, mixed>): (true|\WP_Error)}> */
    protected array $handlers = [];

    protected ?ToolContext $context = null;

    /**
     * Make `$tool` a write tool: how to describe a call before approval, and how to undo a recorded change.
     *
     * @since 0.1.0
     * @param callable(array<string, mixed>): string                       $preview
     * @param callable(array<string, mixed>): (true|\WP_Error)              $undo
     */
    public function handler(string $tool, callable $preview, callable $undo): void
    {
        $this->handlers[$tool] = ['preview' => $preview, 'undo' => $undo];
    }

    /**
     * @since 0.1.0
     */
    public function undoable(string $tool): bool
    {
        return isset($this->handlers[$tool]);
    }

    /**
     * @since 0.1.0
     * @param array<string, mixed> $args
     */
    public function preview(string $tool, array $args): string
    {
        return isset($this->handlers[$tool]) ? (string) ($this->handlers[$tool]['preview'])($args) : '';
    }

    /**
     * @since 0.1.0
     */
    public function open(ToolContext $context): void
    {
        $this->context = $context;
    }

    /**
     * @since 0.1.0
     */
    public function close(): void
    {
        $this->context = null;
    }

    /**
     * The call being run, or null outside an approved chat call.
     *
     * @since 0.1.0
     */
    public function current(): ?ToolContext
    {
        return $this->context;
    }

    /**
     * Record a change made by the call that is open. Returns the change id.
     *
     * @since 0.1.0
     * @param array<string, mixed> $before
     * @param array<string, mixed> $after
     */
    public function record(string $tool, string $objectType, int $objectId, array $before, array $after, string $summary): int
    {
        if ($this->context === null) {
            throw new \LogicException('No tool call is open.');
        }

        return $this->insert([
            'session_id'  => $this->context->sessionId,
            'user_id'     => $this->context->userId,
            'run_id'      => $this->context->runId,
            'call_id'     => $this->context->callId,
            'idem_key'    => $this->context->idempotencyKey(),
            'tool'        => $tool,
            'object_type' => $objectType,
            'object_id'   => $objectId,
            'summary'     => $summary,
            'before'      => $before,
            'after'       => $after,
        ]);
    }

    /**
     * Undo change `$id` for `$userId`. True when it was undone now; a `WP_Error` explains why not.
     *
     * @since 0.1.0
     * @return true|\WP_Error
     */
    public function undo(int $userId, int $id): bool|\WP_Error
    {
        $change = $this->find($id);
        if ($change === null || (int) $change['user_id'] !== $userId) {
            return new \WP_Error('maze_graph_no_change', __('That change does not exist.', 'maze-graph'));
        }
        if ($change['status'] !== 'applied') {
            return new \WP_Error('maze_graph_already_undone', __('That change was already undone.', 'maze-graph'));
        }
        if (!isset($this->handlers[$change['tool']])) {
            return new \WP_Error('maze_graph_no_undo', __('That tool is no longer available, so its change cannot be undone here.', 'maze-graph'));
        }
        if (!$this->markUndone($id)) {
            return new \WP_Error('maze_graph_already_undone', __('That change was already undone.', 'maze-graph'));
        }

        $result = ($this->handlers[$change['tool']]['undo'])($change);
        if ($result !== true) {
            $this->markApplied($id);
        }

        return $result;
    }

    /**
     * The change recorded under an idempotency key (`run:call`), or null.
     *
     * @since 0.1.0
     * @return array<string, mixed>|null
     */
    abstract public function findByKey(string $key): ?array;

    /**
     * @since 0.1.0
     * @return array<string, mixed>|null
     */
    abstract public function find(int $id): ?array;

    /**
     * The latest applied change by one of `$tools` in each of `$sessionIds`: session id => change. One query, for a list.
     *
     * @since 0.1.4
     * @param list<int>    $sessionIds
     * @param list<string> $tools
     * @return array<int, array<string, mixed>>
     */
    abstract public function latestForSessions(array $sessionIds, array $tools): array;

    /**
     * The latest applied change by one of `$tools` to each of `$objectIds`, made by `$userId`: object id => change.
     * One query, for a list screen.
     *
     * @since 0.1.4
     * @param list<int>    $objectIds
     * @param list<string> $tools
     * @return array<int, array<string, mixed>>
     */
    abstract public function latestForObjects(int $userId, string $objectType, array $objectIds, array $tools): array;

    /**
     * The latest applied change by one of `$tools` to one object (a post), whoever made it, or null.
     *
     * @since 0.1.4
     * @param list<string> $tools
     * @return array<string, mixed>|null
     */
    abstract public function latestForObject(string $objectType, int $objectId, array $tools): ?array;

    /**
     * A bounded history projection for one object. Implementations must omit session identifiers, arguments,
     * snapshots, and any other fields not needed by the caller. Older journal adapters may safely return no rows.
     *
     * @param list<string> $tools
     * @return list<array{tool: string, status: string, summary: string, created_at: string}>
     */
    public function forObject(string $objectType, int $objectId, array $tools, int $limit = 20): array
    {
        return [];
    }

    /**
     * @since 0.1.0
     * @param array<string, mixed> $row
     */
    abstract protected function insert(array $row): int;

    /**
     * Flip `applied` to `undone` in one conditional write; false when another request already did.
     *
     * @since 0.1.0
     */
    abstract protected function markUndone(int $id): bool;

    /**
     * @since 0.1.0
     */
    abstract protected function markApplied(int $id): void;

    /**
     * The newest changes, for the Activity page: one person's, or everyone's when `$userId` is 0. Each row has the
     * session's public id as `session_uuid`.
     *
     * @since 0.1.0
     * @return list<array<string, mixed>>
     */
    abstract public function recent(int $userId, string $status = '', int $limit = 50, int $offset = 0): array;

    /**
     * Count the changes visible to the Activity page, optionally restricted to one status.
     *
     * @since 0.1.0
     */
    abstract public function countRecent(int $userId, string $status = ''): int;

    /**
     * The newest change a session made with one of `$tools` that is still applied, or null.
     *
     * @since 0.1.0
     * @param list<string> $tools
     * @return array<string, mixed>|null
     */
    abstract public function latestFor(int $sessionId, array $tools): ?array;

    /**
     * Forget the changes of sessions that are being deleted.
     *
     * @since 0.1.0
     * @param list<int> $sessionIds
     */
    abstract public function forgetSessions(array $sessionIds): void;
}