feat(clickhouse): rename actor columns in ClickHouse adapter only

[lohanidamodar]

Summary

This PR narrows the scope to a ClickHouse-only column rename. The original draft renamed columns and the public API across both adapters — that broke Cloud (which still uses the Database adapter for per-project audit logs) and every library caller. Per product decision, the Database adapter and the public Audit API stay unchanged for this cycle; the Database backend will be deprecated separately.

What changed

• ClickHouse adapter only: userId → actorId, userType → actorType, userInternalId → actorInternalId (columns + matching indexes).
• ClickHouse adapter accepts the legacy userId array key and Query::equal('userId', ...) filter and translates them to the new column internally.
• ClickHouse-backed Log instances expose both actorId (canonical) and userId (legacy mirror) attribute keys so existing callers keep working.
• Log::getActorId(), Log::getActorType(), Log::getActorInternalId() getters added for ClickHouse-aware callers.
• CHANGELOG.md written for 2.4.0 (minor bump from 2.3.2).

What did NOT change

• Public Audit API: Audit::log($userId, ...), Audit::getLogsByUser(...), Audit::countLogsByUser(...), Audit::getLogsByUserAndEvents(...), Audit::countLogsByUserAndEvents(...) keep their original names and signatures.
• Adapter.php abstract contract: getByUser / countByUser / getByUserAndEvents / countByUserAndEvents unchanged.
• Adapter/SQL.php shared base: userId attribute and idx_userId_event index unchanged.
• Adapter/Database.php: completely unchanged — Cloud's per-project audit tables are unaffected.
• Log::getUserId() still present and behaves as before for Database-backed logs.

Migration

• ClickHouse audit tables: setup() will create new tables with actorId / actorType / actorInternalId columns. Existing ClickHouse data is not preserved automatically; this is acceptable because the activity-events surface backed by this schema is not yet in public use.
• No migration is required for Database-backed audit logs.
• Callers may opt in to the new Log::getActorId() / getActorType() / getActorInternalId() getters when reading ClickHouse-backed logs.

Version

2.4.0 — minor bump. No BC break.

Test plan

• vendor/bin/pint --test passes on PHP 8.4
• vendor/bin/phpstan analyse --level max src tests passes
• vendor/bin/phpunit passes against MariaDB 10.11 + ClickHouse 25.11 (88 tests, 841 assertions)

[greptile-apps]

Greptile Summary

This PR scopes the userId→actorId column rename to the ClickHouse adapter only, leaving the public Audit API, the Database adapter, and the shared SQL base class unchanged. Legacy callers are supported through internal translation of userId array keys on write and Query::equal('userId', ...) filters on read.

• ClickHouse schema and indexes are renamed (userId→actorId, userType→actorType, userInternalId→actorInternalId) with corresponding translateAttribute() remapping for WHERE/ORDER-BY queries.
• Log gains three new typed getters (getActorId(), getActorType(), getActorInternalId()); read-path output documents expose both canonical actorId and legacy userId mirror keys.
• CHANGELOG.md added for 2.4.0 with schema change details and migration guidance.

Confidence Score: 4/5

Safe to merge after fixing the Query::select() translation gap; all other read/write paths correctly translate legacy userId keys.

The write path and most query types correctly translate legacy userId/userType/userInternalId references. The one gap is Query::select(): column names are passed as $values rather than $attribute, so translateAttribute is never called on them — a caller passing Query::select(['userId']) hits validateAttributeName before translation and receives an exception.

src/Audit/Adapter/ClickHouse.php — specifically the TYPE_SELECT branch in parseQueries around line 1360.

Important Files Changed

Filename	Overview
src/Audit/Adapter/ClickHouse.php	Renames userId/userType/userInternalId columns to actorId/actorType/actorInternalId in schema, indexes, write path, and query building. Legacy translation works for WHERE/ORDER-BY/IS-NULL queries and write-path array keys, but Query::select() values skip translateAttribute, so Query::select(['userId']) throws at validateAttributeName.
src/Audit/Log.php	Adds getActorId(), getActorType(), and getActorInternalId() typed getters; existing getUserId() is untouched. Changes are additive and safe.
tests/Audit/Adapter/ClickHouseTest.php	Test fixtures and assertions updated to use actor* naming; covers attribute list, index list, batch insert, isNull/isNotNull, and select projection. No test covers Query::select(['userId']) legacy translation.
CHANGELOG.md	New changelog entry for 2.4.0 documenting the ClickHouse-only column rename, legacy compatibility, new Log getters, and migration notes.

Comments Outside Diff (1)

1. src/Audit/Adapter/ClickHouse.php, line 1360-1369 (link)

   The translateAttribute() call at line 1145 is applied to $attribute (from $query->getAttribute()), covering WHERE-clause, ORDER-BY, and similar single-attribute query types. However, the TYPE_SELECT branch iterates over $values — not $attribute — and calls validateAttributeName($column) without first running each column through translateAttribute. Since getAttributes() no longer contains userId, any caller that passes Query::select(['userId', ...]) will receive Exception: Invalid attribute name: userId, breaking the legacy-compatibility contract the PR provides for other query methods.

_{Reviews (3): Last reviewed commit: "Merge branch 'main' into feat/actor-term..." | Re-trigger Greptile}

[greptile-apps]

Version number contradicts PR title and description

The CHANGELOG header says 2.4.0 and explicitly states "This is a non-breaking change for callers of the public API," but the PR title uses the feat! conventional-commit prefix, says "BC break," and states the next tag should be 3.0.0. Additionally, the PR description's renames table lists Adapter::getByActor(), Audit::getLogsByActor(), etc. — but none of those method renames appear in the code; Adapter.php and Audit.php still expose getByUser, countByUser, log(?string $userId, ...). A consumer reading the PR description will look for getByActor() and find it absent. Before merging, the CHANGELOG version and the PR description must agree: either the ClickHouse-only schema rename is a non-breaking 2.x release (matching the code), or the public PHP API methods still need to be renamed to make this a true 3.0.0 BC break.

[greptile-apps]

"Recreated by setup()" is factually incorrect

setup() issues CREATE TABLE IF NOT EXISTS, so an existing table is never touched — it is not dropped and recreated. For any operator upgrading the library against a live ClickHouse instance, the table retains the old userId/userType/userInternalId columns, and every query the new code emits (which references actorId) will fail immediately. The phrase "will be recreated by setup()" may mislead operators into believing no manual action is required before redeploying. The sentence should clarify that setup() only creates the table for fresh installations, and that existing installations require the ALTER TABLE ... RENAME COLUMN steps listed below before redeploying.