<?php
/**
 * The port for a session's transcript and run state.
 *
 * @package MazeAi
 * @since   0.1.0
 */

declare(strict_types=1);

namespace MazeAi\Chat;

defined('ABSPATH') || exit;

/**
 * What the run loop needs from storage. Callers have already checked that the session belongs to the user; the
 * production store is `MazeAi\Sessions\DatabaseConversationStore`.
 *
 * Run states: `idle` (never ran), `running`, `awaiting` (paused until a person approves or refuses a
 * call), `done`, `cancelled`, `error`. One run per session at a time. A session may be the hidden child of another
 * (a sub-agent's conversation); `agent` names the agent definition that answers in it.
 * `run()` may also include the normalized session `permission_mode`; consumers default to Ask when an older store
 * omits it.
 *
 * Contract version 5 adds bounded model-context reads and taint lookup. Version 4 adds bounded keyset pages for the chat history. Version 3 adds `lastUserMessage` and `renewStep`;
 * version 2 added `entriesAfter`, `resumeRun`, `runsStartedSince`, `child` and `agent` on `run()`).
 *
 * @since 0.1.0
 */
interface ConversationStore
{
    /**
     * The transcript in order, each entry with its `seq`.
     *
     * @since 0.1.0
     * @return list<array<string, mixed>>
     */
    public function entries(int $sessionId): array;

    /**
     * The newest page of transcript entries, starting at a user-turn boundary when possible.
     *
     * @since 0.1.0
     * @return array{entries: list<array<string, mixed>>, has_more: bool, before_seq: int|null}
     */
    public function latestPage(int $sessionId, int $turnLimit = 20): array;

    /**
     * A page older than `$beforeSeq`, using sequence-keyset pagination rather than an offset.
     *
     * @since 0.1.0
     * @return array{entries: list<array<string, mixed>>, has_more: bool, before_seq: int|null}
     */
    public function pageBefore(int $sessionId, int $beforeSeq, int $turnLimit = 20): array;

    /**
     * A bounded recent transcript window for a model call or context preview. Compact mode may include its latest
     * visible summary even when that summary is older than the window.
     *
     * @since 0.1.4
     * @return list<array<string, mixed>>
     */
    public function contextEntries(int $sessionId, bool $includeCompactionSummary = false): array;

    /** Whether any visible-in-practice tool output has been marked tainted in this transcript. */
    public function hasTaintedToolResults(int $sessionId): bool;

    /** Check whether the persisted high-water sequence matches the session's entry counter without loading entries. */
    public function transcriptMatchesCount(int $sessionId, int $expectedCount): bool;

    /**
     * Append one line; returns it with its `seq`.
     *
     * @since 0.1.0
     * @param array<string, mixed> $entry
     * @return array<string, mixed>
     */
    public function append(int $sessionId, array $entry): array;

    /**
     * @since 0.1.0
     * @return array{id: string|null, status: string, step: int, reason: string|null, agent: string, permission_mode?: string}
     */
    public function run(int $sessionId): array;

    /**
     * The lines after sequence number `$afterSeq`, in order (the app fetches only what is new).
     *
     * @since 0.1.0
     * @return list<array<string, mixed>>
     */
    public function entriesAfter(int $sessionId, int $afterSeq): array;

    /**
     * The newest user message that is still visible (not superseded by a rewind), with its `seq`, without reading
     * the whole transcript.
     *
     * @since 0.1.0
     * @return array<string, mixed>|null
     */
    public function lastUserMessage(int $sessionId): ?array;

    /**
     * Start a new run unless one is running; returns its id, or null when the session is busy.
     *
     * @since 0.1.0
     */
    public function startRun(int $sessionId): ?string;

    /**
     * Take the lease on one step of a running run. False when the step was already taken, the run moved on, or it
     * is not running: the caller then reports the current state instead of calling the model twice.
     *
     * @since 0.1.0
     */
    public function claimStep(int $sessionId, string $runId, int $step, int $leaseSeconds): bool;

    /**
     * Extend the lease of a step this request still holds, before it does anything that cannot be repeated. False
     * when the step is no longer running (cancelled, finished or taken over): the caller must then stop at once.
     *
     * @since 0.1.0
     */
    public function renewStep(int $sessionId, string $runId, int $step, int $leaseSeconds): bool;

    /**
     * Release the lease: the run goes on at `$nextStep`, or ends with `$status` and `$reason`. No effect on a run
     * that was cancelled meanwhile.
     *
     * @since 0.1.0
     */
    public function finishStep(int $sessionId, string $runId, int $nextStep, string $status, ?string $reason = null): void;

    /**
     * Continue a run that waits for an approval: `awaiting` becomes `running` at the same step, in one
     * conditional write, so a double click resumes once. False when it was not waiting.
     *
     * @since 0.1.0
     */
    public function resumeRun(int $sessionId, string $runId): bool;

    /**
     * Stop a running or waiting run. False when nothing was running.
     *
     * @since 0.1.0
     */
    public function cancelRun(int $sessionId, string $runId): bool;

    /**
     * Tokens used site-wide since midnight UTC, for the daily cap.
     *
     * @since 0.1.0
     */
    public function tokensToday(): int;

    /**
     * Replies a person started since a Unix time, across their sessions, for the per-person rate limit. A reply
     * starts with a new message, an edit or a regenerate (an `event` line carrying `regenerate: true`).
     *
     * @since 0.1.0
     */
    public function runsStartedSince(int $userId, int $since): int;

    /**
     * Create the hidden child session a sub-agent works in, owned by the parent's user. Returns its id.
     *
     * @since 0.1.0
     */
    public function child(int $parentId, string $agent): int;
}