test(sync): add a multi-device sync integration test harness

[mohamede1945]

Stacked on #317 (feat/sync-status). Review that one first.

Summary

Adds an end-to-end integration-test harness for sync. Each test drives the public QuranDataService / AuthService of several simulated devices against one fake /v1/sync server. The tests use only the public API and server state, so the same tests will run unchanged against a rewritten sync engine.

Per device: a real in-memory database, the real Ktor/OkHttp client, and a production AppGraph built per device. Only the database and the OIDC auth layer are replaced. The network is faked only at the boundary, with a loopback HTTP FakeSyncServer.

This PR adds the harness plus smoke tests; the scenario suite comes in the next stacked PRs.

What's included

• FakeSyncServer mirrors the backend's sync rules and side effects:

  • validation (422) before the lastMutationAt head check (409), and atomic POSTs;
  • pagination, with Favorites as the virtual __default__ collection;
  • bookmark and membership cascades;
  • reading-session upsert and move, and reading-bookmark slot collapse;
  • duplicate names → 409 UniqueViolationError;
  • protected collections → 403;
  • htmlStrip, and note UPDATE accepting only body.

• Errors use the API-gateway envelope by default; the bare backend envelope can be switched on. details.mutationIndex (from the backend PR) is off by default and can be switched on.

• Fault injection:

  • a lost response after commit, a blocked POST, network down;
  • failing N requests, or rejecting a chosen mutation;
  • web writes between GET and POST or between pages.

  A request log is kept for assertions.

• The harness (syncScenario { }) gives you devices, a web actor, syncNow() returning a SyncRun (status, skipped, requests), syncUntilQuiescent (rotating order, unchanged head, no skipped runs), convergence checks and a duplicate check after every scenario.

• knownIssue(id, description, expect) is a strict expected failure:

  • only an AssertionError matching expect counts as the issue reproducing;
  • harness errors, bugs in the fake, and timeouts fail the test;
  • if the block passes, the test fails with "appears fixed; remove knownIssue".

• Smoke tests:

  • harness paths: first sync, a note and collection round-trip, web changes, repeat syncs as no-ops, a transient 500, restart, an expired session, logout, a lost response, a blocked POST, a head change between pages, pagination, a gate-skipped run, and the bare envelope;
  • one knownIssue (S7: editing a synced note gets 422 forever);
  • tests of the fake server itself against the backend contract.

• Deleted SynchronizationClientIntegrationTest: 4 @Ignored tests against the live testing API, using a JWT that had expired.

Seams

• schedulerTimings: SchedulerTimings? = null on SynchronizationClientBuilder.build and SyncEnginePipeline.setup. Both are @HiddenFromObjC, and the generated Shared.h is unchanged. In tests, a run that keeps failing gives up in about 0.3 s instead of about 13 s.
• One accepted Metro warning ("unused DriverFactory") in the device graph. The JVM DriverFactory is final, and makeDatabase caches one database per process, so each device binds its own in-memory database directly. This goes away when persistence is reworked.

Known differences from the backend

• Text tag stripping follows sanitize-html's rules but decodes only common named entities. Its KDoc lists the unverified assumptions.
• Case folding for non-ASCII names uses Kotlin's root locale, not the Postgres collation.
• Error messages are close to the backend's but not identical.

Tests

• ./gradlew :sync-pipelines:jvmTest --rerun: 119 tests, 0 failures. The new tests take about 2 s, and were stable across 8 consecutive reruns.
• ./gradlew allTests --continue: passes on all targets.

Reviewed in two rounds by a separate reviewer; all findings are addressed.

🤖 Generated with Claude Code

Cleanup (rebased 2026-10-14)

• CI flake fixed in the harness: syncNow() repeats a "sync now" that a scheduler dropped at the end of a run. After a skipped run, the harness waits for the sign-out. It was verified with 50 loaded runs and no failures.
• Removed redundant comments and the unused metadataOnly path.
• Smoke and path tests that duplicate catalog scenarios are deleted in the PR that adds the covering scenario (test(sync): add the P0 sync integration scenarios #319, test(sync): add the P1 sync integration scenarios #320, feat(sync)!: run sync on the sync-v2 engine and plain tables #323).
• Added an Integration Tests section to AGENTS.md: how to write scenarios, knownIssue/allowDuplicates, and how to model a new synced type in FakeSyncServer.