hardening: enhance PHPDoc for improved static analysis

[somethingwithproof]

This issue proposes enhancing PHPDoc blocks across core library files to improve the accuracy of static analysis tools like PHPStan.

Key focus areas include:

1. Defining precise array shapes for complex data structures (e.g., $user, $config).
2. Adding missing type information for function parameters and return values.
3. Reducing the number of mixed and array types where more specific types are known.

Improved static analysis helps catch subtle bugs and ensures that architectural assumptions remain valid as the codebase evolves.