refactor(usage): extract buffering into a standalone Accumulator

[loks0n]

What

Extracts the in-memory metric buffering out of Usage into a dedicated Accumulator class that consumers create themselves against an adapter.

• Accumulator owns collect(), flush(), and the buffer. It exposes raw signals — count() (buffered entries) and elapsedSeconds() (since last flush) — and leaves the flush policy to the caller.
• Usage is now a pure adapter facade: no buffer, no collect/flush/shouldFlush, no threshold config.

Why

• Separates "what's buffered" from "how to query/store" — Usage no longer carries mutable buffer state, which is the wrong place for it in coroutine/multi-tenant setups where each context wants its own buffer.
• Drops the shouldFlush() + setFlushThreshold/setFlushInterval policy machinery in favour of primitives the caller composes:

  $accumulator = new Accumulator($adapter);
  $accumulator->collect('bandwidth', 5000, Usage::TYPE_EVENT);
  if ($accumulator->count() >= 5000 || $accumulator->elapsedSeconds() >= 10) {
      $accumulator->flush();
  }

Tests

• New AccumulatorTest — DB-free, uses a recording fake adapter to cover event summing, gauge last-write-wins, per-type batch separation, partial-failure buffer retention, and the signals/validation.
• Buffer tests removed from UsageBase (the real-DB addBatch round-trip stays covered by testAddBatchEvent/testAddBatchGauge).

Net -17 LoC overall.

Note: vendor/ isn't installed in the worktree, so I couldn't run composer test/check locally. CI should validate.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR moves metric buffering out of Usage and makes tenant scope explicit. The main changes are:

• Added a standalone Accumulator for collect(), flush(), buffer count, and elapsed-time signals.
• Simplified Usage into an adapter facade with tenant arguments on read and mutation methods.
• Updated ClickHouse and Database adapters to take tenant scope per call or per batch row.
• Added a Tenant decorator for callers that want a tenant-bound view.
• Updated README examples, tests, and benchmarks for the new API.

Confidence Score: 5/5

The refactor is narrowly scoped and covered by updated unit and adapter tests.

No code issues were identified in the reviewed changes, and the API split is consistently reflected across implementation, tests, benchmarks, and documentation.

T-Rex Logs

What T-Rex did

• Compared base and head states to confirm that the head now includes an Accumulator and that Usage no longer owns collect and flush.
• Validated that the new Accumulator reports countAfterCollect as 3 unique entries and that separate event and gauge batches are emitted.
• Verified tenant-based partitioning of event rows into tenantA and tenantB, the last-write-wins gauge value of 12, and the exposure of elapsedSeconds.
• Confirmed the system retains a failed event batch with countAfterFailedFlush equal to 1 and that a retry completes successfully with exitCode 0.
• Compared the base and head code for policy methods and observed that mutable methods like collect and flush are removed, with read signatures now starting with tenant.
• Verified that Usage::addBatch accepts mixed tenant rows and that Tenant::addBatch overwrites or stamps rows with tenant-bound data while forwarding getTotal, find, count, purge, sum, findDaily, sumDaily, and sumDailyBatch under the tenant bound context.

_{Ran code and verified through T-Rex}

_{Reviews (9): Last reviewed commit: "fix(clickhouse): reject empty tenant on ..." | Re-trigger Greptile}

[greptile-apps]

Preserve tenant mismatches

This wrapper overwrites any existing tenant on each metric row. If a caller accidentally passes a mixed-tenant batch into a bound tenant view, the rows are all written under the bound tenant with no signal, which can misattribute usage. Rejecting rows that already carry a conflicting tenant would keep this decorator from hiding a bad producer.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[greptile-apps]

Validate tenant scope

The direct Usage methods now take a tenant, but this path forwards an empty string unchanged. In shared-table ClickHouse mode that becomes a tenant = '' filter, so a caller with a missing tenant can silently read an empty scope instead of failing like Accumulator and Tenant do. The same guard should be applied before forwarding tenant-scoped reads and mutations.

[greptile-apps]

Canonicalize nested tags

ksort() only normalizes the top-level tag keys before hashing. If a tag value is itself an array, the same logical tags with nested keys in a different insertion order still produce different hashes, so event values split into multiple buffered rows and gauges can keep more than one pending value for the same metric identity. Recursively sorting array tag values before json_encode() would keep the buffer identity stable.