<?php

declare(strict_types=1);

namespace Plugin\tnt_mcp\src\Mcp\Backend;

/**
 * The ambient state a single backend invocation wants to see — the *input* of
 * {@see GlobalStateSandbox::enter()}. Value object: no behaviour, no defaults beyond "empty".
 *
 * Two of the six are not plain replacements, and the difference is deliberate:
 *
 * - `$server` is **merged over** the ambient `$_SERVER` (our keys win). A backend controller runs
 *   inside a real PHP process that still needs `DOCUMENT_ROOT`, `SCRIPT_NAME`, `argv`, … — replacing
 *   `$_SERVER` wholesale would break shop code that has nothing to do with the invocation.
 * - `$session` **replaces** `$_SESSION` wholesale. That is the whole point: the invocation must not
 *   see, and must not be able to write into, the caller's session (an MCP request runs inside the
 *   *frontend* session). It gets a purpose-built array holding exactly `AdminAccount`, `jtl_token`
 *   and whatever the action needs.
 *
 * `$_REQUEST` is not a field: it is derived as `$post + $get` (POST wins), mirroring PHP's default
 * `request_order=GP`. Handing it in separately would only allow it to disagree with `$_GET`/`$_POST`.
 */
final readonly class SandboxState
{
    /**
     * @param array<string,mixed> $post    replaces $_POST
     * @param array<string,mixed> $get     replaces $_GET
     * @param array<string,mixed> $server  MERGED over the existing $_SERVER (these keys win)
     * @param array<string,mixed> $session REPLACES $_SESSION wholesale
     * @param array<string,mixed> $cookie  replaces $_COOKIE
     * @param array<string,mixed> $files   replaces $_FILES
     */
    public function __construct(
        public array $post = [],
        public array $get = [],
        public array $server = [],
        public array $session = [],
        public array $cookie = [],
        public array $files = [],
    ) {
    }
}
