chore(php): backed enums for log/ban/web-permission columns (#1290)

[rumblefrog]

Summary

Closes part of #1290. Phase D from the umbrella — backed PHP-side enums wrapping the on-disk column types. Schema is unchanged.

• D.1: LogType (string-backed) wraps :prefix_log.type enum('m','w','e'). Log::add(string $type) signature now takes LogType. Log.php's switch-based search WHERE builder also refactored to a LogSearchType enum + whereClause() method.
• D.2: BanType (int-backed) wraps :prefix_bans.type tinyint.
• D.3: BanRemoval (string-backed; departure from the issue body — the on-disk column is varchar(3) NULL not int) wraps :prefix_bans.RemoveType and :prefix_comms.RemoveType. Cases D / U / E.
• D.4: WebPermission (int-backed) wraps the ADMIN_* integer-bitmask flags from web/configs/permissions/web.json (mirrors init.php's defined constants — both shapes coexist for backward compatibility). 31 cases. Static helpers WebPermission::mask(...$flags) and WebPermission::fromMask(int).

HasAccess() signature now WebPermission|int|string $flags — the legacy HasAccess(ADMIN_OWNER | ADMIN_X) shape and the modern HasAccess(WebPermission::mask(...)) shape both work.

Wire-format unchanged

composer api-contract clean — no Perms.ADMIN_* shape change; the JS contract still emits the same constants (the enum is purely a PHP-side wrapper).

Notable decisions (from the review)

1. BanRemoval is string-backed, not int — the on-disk column is varchar(3) NULL. Reading from disk: null / '' means the ban is still active; D/U/E are terminal states. Helper docblocks call this out so future readers know the contract.
2. HasAccess() is NOT variadic — the docblock + AGENTS.md anti-pattern row use the correct WebPermission::mask(...) shape (NOT HasAccess(WebPermission::Owner, WebPermission::AddBan), which would bind the second flag as $aid and crash).
3. Regression test pinning WebPermission cases to web/configs/permissions/web.json (WebPermissionTest::testWebPermissionEnumMatchesWebJson). Drift now fails the gate.
4. Unit tests for WebPermission::fromMask covering known-bit round-trip, zero, unknown-bit silent drop, and 2^31 high-bit on 64-bit PHP.
5. Deliberately legacy call shapes preserved (with rationale documented in the AGENTS.md anti-patterns):
   • HasAccess(ALL_WEB, $aid) — ALL_WEB is a derived rolled-up bitmask, not a flag.
   • HasAccess(SM_RCON . SM_ROOT) — SourceMod char-flag string, not an int bitmask.
   • Runtime-dynamic HasAccess($flag) in AdminTabs, SmartyCustomFunctions, View/Perms, etc. — value is computed at runtime from JSON config.
   • RemoveType = 'E' literals in PruneBans / PruneComms static SQL strings (inline predicates, not bound values).

sbError() now maps to LogType cases

$entry = match ($errno) {
    E_USER_ERROR   => [LogType::Error,   'PHP Error',   'Fatal Error'],
    E_USER_WARNING => [LogType::Warning, 'PHP Warning', 'Error'],
    E_USER_NOTICE  => [LogType::Message, 'PHP Notice',  'Notice'],
    default        => null,
};

Closing invariants

$ rg "Log::add\('[a-z]'" web/        # empty
$ rg "HasAccess\(\s*ADMIN_" web/     # only the docblock reference
$ rg "varchar\(1\)" web/includes AGENTS.md ARCHITECTURE.md  # empty

Test plan

• ./sbpp.sh phpstan clean (225 files)
• ./sbpp.sh test 393 tests pass (5 new WebPermissionTest cases)
• ./sbpp.sh ts-check clean
• ./sbpp.sh composer api-contract byte-identical
• PHPStan baseline net -12 lines vs main (2 ignore blocks dropped after PR3's int-cast on mktime hour/minute args)