refactor(types): tighten $REQUEST_JSON + ApiResponse return shapes (#405)

class/xion/ApiResponse.php

@@ -38,11 +38,18 @@ public function __construct()
     }
 
     /**
-     * Build a success response.
+     * Build a success response envelope.
      *
-     * @param array<string,mixed> $data Response data.
+     * The returned array always includes `status: 'success'` and
+     * `errorCode: ''`; any keys supplied in `$data` are merged on top
+     * (caller-supplied keys win, since `array_merge` keeps the rightmost
+     * value for duplicate keys). The envelope is wrapped by
+     * `JsonResponder::responseArray()` so the final REST shape is
+     * `{ Result: true, Data: { status: 'success', errorCode: '', ... } }`.
      *
-     * @return array<string,mixed> API response.
+     * @param array<string,mixed> $data Domain-specific data to merge into the envelope.
+     *
+     * @return array<string,mixed> Success envelope with caller keys merged.
      */
     public function success(array $data = []): array
     {
@@ -53,11 +60,15 @@ public function success(array $data = []): array
     }
 
     /**
-     * Build a failure response.
+     * Build a failure response envelope.
      *
-     * @param string $errorCode Error code.
+     * The shape is exactly three keys — `status`, `errorCode`,
+     * `errorMessage` — and never carries caller-supplied data. The
+     * PHPDoc uses the array-shape form so static analysis can
+     * distinguish failure responses from success responses by the
+     * presence of `errorMessage` (#405, eval report PR #401 § 2).
      *
-     * @return array<string,string> API response.
+     * @return array{status: 'failure', errorCode: string, errorMessage: string}
      */
     public function failure(string $errorCode): array
     {

class/xion/ControllerBase.php

@@ -129,9 +129,14 @@ abstract class ControllerBase
     private CsrfProtectionPolicy $csrfProtectionPolicy;
 
     /**
-     * Rest post
+     * Decoded JSON request body (REST POST / PUT / PATCH / DELETE only).
      *
-     * @var array
+     * Populated by `JsonResponder::inputJsonToArray()` for state-changing
+     * REST requests; an empty array otherwise. Parameterizing the type
+     * lets Phan / IDE follow value types through controller code
+     * (#405, eval report PR #401 § 2).
+     *
+     * @var array<string,mixed>
      */
     protected array $REQUEST_JSON = [];