feat: migrate audit to query-lib schema objects

[abnegate]

Summary

Canonical continuation of utopia-php/audit#133 in packages/audit, following the approved move to the monorepo. audit#133 is closed in favour of this.

• Return typed Attribute and Index schema objects and use Collection for database setup.
• Adapt ClickHouse schema, DDL and encoding paths to value objects while preserving existing fields, indexes, null handling and tenant behavior.
• Require the Database dev-feat-query-lib branch from Packagist, with no VCS repository override and no inline alias; declare PDO MySQL and Swoole test extensions.
• Cover nullable logs, schema defaults and string filtering.

Dependency shape

CLAUDE.md requires packages to depend on siblings through Packagist constraints rather than repository overrides. The branch originally carried a repositories entry pointing at github.com/utopia-php/database.git; that is removed. Packagist already publishes every branch of utopia-php/database, dev-feat-query-lib included, so "utopia-php/database": "dev-feat-query-lib" resolves on its own — and resolves to the branch head rather than to whatever commit an override happened to capture.

utopia-php/validators is ^1.0 here, matching main since #251.

Blocked on

utopia-php/database is still a branch requirement, which is the one thing here that is not a released constraint. It becomes ^8.0 (or whatever utopia-php/database#823 tags as) the moment that PR is merged and tagged, and this PR should not land before then. Nothing else in this branch is waiting on anything.

Verification

Both registry and linked modes passed:

• Unit: 22 tests, 106 assertions.
• E2E: 92 tests, 1,023 assertions, including MariaDB and ClickHouse.

Pint, PHPStan, Rector, Composer validation and monorepo validation passed. composer update --dry-run in packages/audit with the override removed resolves utopia-php/database (dev-feat-query-lib 11f8380) plus query 0.6.1, validators 1.0.1 and async 0.1.1, all from Packagist.

No package split, release, tag or merge has been performed.

---

Do not merge before utopia-php/database 8.0.0 is tagged — the constraint flips to 8.* in one commit first (report 17 release path).

Fixes from the 2026-09-23 review

The audit Query constants now come from the query library (10.11). Utopia\Audit\Query re-declared its 25 legacy
TYPE_* constants (TYPE_EQUAL … TYPE_CURSOR_BEFORE) as string literals that copied Utopia\Query\Method's values.
Each one is now Method::X->value:

• The values are the same, and the constants are still untyped public constants, so consumers need no change.
• If utopia-php/query changes a method's value, the constant picks it up instead of keeping the stale string.
• If a case is renamed or removed, PHPStan fails at the constant, and Query throws the first time it is used.

QueryTest::testConstantMatchesMethod checks that every TYPE_* constant is a Method value.

Commits

• 7c9c829 refactor(audit): read Query's TYPE_* constants from the Method enum

🤖 Generated with Claude Code

[abnegate]

@greptile-apps review

[abnegate]

@greptileai review the current head 394aa7f. The September 4 request using the older bot handle did not start a review; this uses the currently documented trigger.

[abnegate]

@greptileai review

[greptile-apps]

Confidence Score: 4/5

The PR is not ready to merge because the audit package still consumes its database sibling through a mutable development-branch constraint, contrary to the repository’s package-boundary requirement.

Findings

1.  Mutable Sibling Dependency ▶

Fix with agent prompt

### Issue 1
packages/audit/composer.json:undefined-30
This package replaces the released `utopia-php/database` dependency with the mutable `dev-feat-query-lib` branch and adds a direct VCS repository override at lines 38–41. The repository requires independent packages to consume siblings through Packagist constraints. This requirement must be satisfied before merging so installs use the supported distribution boundary rather than mutable branch contents.

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!

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

The PR migrates the audit adapters from array-shaped schema definitions to typed database Attribute, Index, and Collection objects while retaining database and ClickHouse behavior.

• Updates ClickHouse schema generation, insert encoding, and column/index handling for typed objects.
• Updates database setup to pass a typed collection definition.
• Adds behavioral coverage for nullable fields, full-length user identifiers, defaults, and string filtering.
• Removes the direct VCS repository override added earlier in the PR.

_{Reviews (5) · Last reviewed commit: "chore(audit): take the database branch f..."}

[abnegate]

@greptileai review

[abnegate]

Both findings addressed at 4e53dd58.

Finding 1 — tests mirror schema internals: fixed.

DatabaseTest::testSchemaValueObjectsAndNullableLog and ClickHouseTest::testPremiumGeoAttributesAreOptionalStrings are gone. Before deleting anything I broke each property in the schema and checked a behavioural test actually goes red, so the coverage is proven and not assumed:

schema change	outcome
drop filters: ['json'] on data	17/17 DatabaseTest red — Attribute "data" has invalid type
drop filters: ['datetime'] on time	testLogByBatch red
idx_userId_event Index::key → Index::unique	17/17 red (createLogs() writes duplicate userId+event pairs)
userId required: false → true	17/17 red
userId size 255 → 128	testUserIdAcceptsFullKeyLength red
idx_userId_event attributes ['userId','event'] → ['event','userId']	green

That last row is the interesting one. The swap reaches the real DDL (KEY idx_userId_event (event, userId)) and all 16 remaining tests still pass, because index column order is a query-planner concern with no behaviour observable through the audit API. No test can ever guard it — which is exactly why asserting it only compared the schema against a second copy of itself.

One property was not otherwise reachable, so it is replaced rather than dropped: userId's size is now covered by testUserIdAcceptsFullKeyLength, which writes a key-length user id and reads it back.

The ClickHouse geo flags are fully subsumed by the existing testPremiumGeoRoundTrip, which writes all nine geo fields and asserts each round-trips unchanged; required is covered by every test's setUp(), which writes logs carrying no geo fields at all.

Finding 2 — ext-swoole: this one is a false positive, and I've left the requirement in place.

The premise is right (nothing under packages/audit mentions Swoole — grep -rniE 'swoole|Coroutine|WaitGroup|\bgo\(' over src/, tests/ and the README returns nothing) but the requirement is transitive, not local. utopia-php/database@dev-feat-query-lib calls it unguarded:

// vendor/utopia-php/database/src/Database/Database.php:1442
private function getEventContext(): int
{
    $context = Coroutine::getCid();

getEventContext() backs silent() / areEventsSilenced(), which deleteDocuments() uses — the path Audit::cleanup() takes, which every test hits in setUp(). Note line 2848 in the same file does guard with extension_loaded('swoole'); line 1442 does not, and utopia-php/database declares no ext-swoole of its own.

I pushed the removal first and CI proved it: test (audit) went to 17 errors, Class "Swoole\Coroutine" not found, and it reproduces locally with the extension unloaded. Dropping the requirement doesn't make the package installable without Swoole, it just converts a clear resolution-time error into 17 runtime fatals — so the declaration stays, per the house preference for declaring real ext-* requirements over --ignore-platform-reqs.

The real fix belongs upstream (guard line 1442 like 2848, or declare ext-swoole in utopia-php/database); tracking that separately rather than in this PR.

Verified at 4e53dd58: unit OK (22 tests, 106 assertions), e2e OK (92 tests, 956 assertions), and bin/monorepo check audit — pint, phpstan level 5, rector — all pass.

[abnegate]

@greptileai review

[walter-o-brien]

🔍 OpenCodeReview found 2 issue(s) in this PR.

• ✅ Successfully posted inline: 2 comment(s)

[ChiragAgg5k]

Audit now lives in packages/audit in appwrite/appwrite (appwrite/appwrite#13955), and this copy is being retired. @abnegate, please re-open this against packages/audit there if you still want it.