feat(clickhouse): optional retention TTL on the raw events table

[levivannoort]

Ports the retention-TTL feature onto main directly (the branches have diverged, so the earlier dev→main PR #23 doesn't apply — this supersedes it).

What

Adds an optional retention window (days) to the ClickHouse adapter. When set, setup() applies an idempotent TTL to the raw events table so rows older than the window are dropped by background merges. The aggregated events_daily table — which backs long-term usage/billing history — is left untouched. Null (the default) disables retention and actively strips any TTL a previous run applied, keeping setup() re-runnable.

Style note

Exposed as a readonly constructor property rather than a getter/setter, matching the adapter's other config fields — more coroutine-safe (no post-construction mutation).

Verification

• composer check (phpstan): clean
• vendor/bin/pint --test: pass
• Constructor validation (rejects non-positive days) verified standalone
• TTL DDL assertion added to ClickHouseSchemaTest (integration-gated on a live ClickHouse, like the rest of that class)

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR adds an optional retention window (days) to the ClickHouse adapter. When set, setup() runs an idempotent ALTER TABLE … MODIFY TTL on the raw events table; when null, it issues REMOVE TTL and swallows the ClickHouse error that fires when no TTL was previously set.

• src/Usage/Adapter/ClickHouse.php: new ?int $retention constructor parameter validated ≥ 1; applyEventsRetention() called inside setup() after the events table is created and before the daily table; error-swallowing dual-anchors on Code: 36 + TTL to avoid masking unrelated BAD_ARGUMENTS failures; the events_daily table is intentionally left untouched.
• tests/Usage/Adapter/ClickHouseSchemaTest.php: integration test asserts the DDL contains the TTL clause on the events table and no TTL on the daily table; a unit-level test exercises the constructor guard for non-positive retention values without requiring a live ClickHouse instance.

Confidence Score: 5/5

Safe to merge — the change is narrowly scoped to a new optional parameter, the DDL path is gated behind a non-null check, and the idempotency guard for the REMOVE TTL case uses stable dual anchoring.

The retention value is typed as int, validated positive at construction, and only ever interpolated as a bare integer literal into the SQL — there is no injection surface. The applyEventsRetention() call is sequenced after the events table creation, so it can never race with a missing table. The error-swallowing logic is tighter than in the first iteration (dual-anchored on code + keyword). No functional defects were identified.

No files require special attention.

Important Files Changed

Filename	Overview
src/Usage/Adapter/ClickHouse.php	Adds optional ?int $retention constructor parameter with positive-value guard; applyEventsRetention() issues MODIFY TTL or REMOVE TTL as an idempotent post-creation ALTER; error-swallowing for the no-TTL case is anchored on both Code: 36 and the word TTL to avoid catching unrelated BAD_ARGUMENTS errors; SQL interpolation of $this->retention is safe because PHP types it as int and the validation rejects non-positive values.
tests/Usage/Adapter/ClickHouseSchemaTest.php	Adds two tests: testRetentionAppliesTtlToEventsTableOnly (integration, requires live ClickHouse) verifies the DDL contains TTL toDateTime(time) on the events table and no TTL on the daily table; testRetentionRejectsNonPositiveDays exercises constructor-time validation without a network connection via PHP 8 named argument syntax. Test isolation uses a unique namespace.

_{Reviews (2): Last reviewed commit: "fix(clickhouse): anchor REMOVE TTL guard..." | Re-trigger Greptile}