docs(v3): document property-test suite structure (catalog/fixture/e2e)

Add a README for the eql_v3 property tests describing the three suites, the
shared all-pairs oracle engine, why ciphertext can't be Arbitrary-derived, and
the conventions/footguns (not under scalars::, e2e gated behind proptest-e2e,
shrinking disabled for e2e). Reference it from CLAUDE.md's Testing section.

Author: tobyhede

CLAUDE.md

@@ -29,6 +29,7 @@ This project uses `mise` for task management. Common commands:
 - Run SQLx tests directly: `mise run test:sqlx`
 - Run SQLx tests in watch mode: `mise run test:sqlx:watch`
 - Tests are located in `tests/sqlx/` using Rust and SQLx framework
+- Property-based tests for the `eql_v3` encrypted scalar domains live in three suites — **catalog** (pure-Rust catalog invariants, no DB), **fixture** (oracle over committed ciphertext), and **e2e** (oracle over fresh end-to-end encryption, gated behind the `proptest-e2e` cargo feature). The structure, the shared all-pairs oracle engine, and the conventions/footguns (e.g. why they must not live under `scalars::`) are documented in `tests/sqlx/tests/encrypted_domain/property/README.md`.
 - Verify the scalar matrix coverage snapshot: `mise run test:matrix:inventory` (no database required). ONE committed `tests/sqlx/snapshots/matrix_tests.txt` baseline pins the token-normalized set of `scalars::<T>::*` test names so a silently dropped/renamed/`#[cfg]`-gated test fails CI's `matrix-coverage` job. The task discovers the present scalar types from the test binary's `--list` and cross-checks them against `cargo run -p eql-codegen -- list-types`, so a catalog type missing its matrix wiring also fails. When you change which matrix tests the macro emits, regenerate and commit the single snapshot in the same change. See `tests/sqlx/snapshots/README.md`.
 
 ### Build System

tests/sqlx/tests/encrypted_domain/property/README.md

@@ -0,0 +1,109 @@
+# Property-based tests for the `eql_v3` encrypted scalar domains
+
+These tests assert that SQL operator results on the `eql_v3` encrypted-domain
+types agree with a **plaintext oracle** across a *generated* input space — the
+fixed-pivot scalar matrix only checks hand-picked values, so property tests are
+what catch operator/oracle disagreements across the whole value space. Origin:
+CIP-3141.
+
+## The three suites
+
+The harness is **one unit-level suite plus two integration suites**. They are
+named for what they operate on, not by an abstract tier letter:
+
+| Suite | Location | Kind | Inputs | DB / creds |
+|-------|----------|------|--------|------------|
+| **catalog** | [`crates/eql-scalars/src/proptest_invariants.rs`](../../../../../crates/eql-scalars/src/proptest_invariants.rs) | unit (pure Rust) | generated terms / kinds | none — runs in fork CI |
+| **fixture** | [`fixture_oracle.rs`](./fixture_oracle.rs) | integration | committed fixture corpus (real ciphertext) | shared test DB |
+| **e2e** | [`e2e_oracle.rs`](./e2e_oracle.rs) | integration | freshly generated plaintexts, encrypted each run | shared test DB **+ ZeroKMS creds** |
+
+Plus [`edge_cases.rs`](./edge_cases.rs): example-based unit tests for
+NULL propagation, blockers raising on unsupported operators (including the
+native-`jsonb` `->`/`@>` domain-fallback paths), `timestamptz` ordering
+deferral, and CHECK rejection of malformed payloads.
+
+### catalog — catalog invariants, no database
+
+Pure-Rust `proptest` over the `eql-scalars` catalog: term/operator/extractor
+consistency, "every blocker is non-`STRICT` + `plpgsql`", payload-key set ==
+declared terms, integer-range ordering. No DB, no encryption, no creds, so it
+runs in the lean `cargo test -p eql-scalars` path (and on fork PRs). This is the
+only suite where `proptest` shrinking is meaningful and enabled.
+
+### fixture — oracle over committed ciphertext
+
+Runs the shared all-pairs oracle engine over the real, committed fixture corpus
+(`fixtures.eql_v2_<T>.sql`, generated by `cipherstash-client` during
+`mise run test:sqlx:prep`). `proptest` selects a sub-multiset of fixture rows
+(with repeats), and the engine checks **every ordered pair**. No new encryption,
+so it runs whenever the fixtures are present, and it generalises across the whole
+catalog for free (every fixtured type gets an `eq_oracle`, ordered types also get
+an `ord_oracle`).
+
+### e2e — oracle over fresh end-to-end encryption
+
+Same oracle engine, but each case **generates fresh random plaintexts and
+encrypts them end-to-end through ZeroKMS** (one batched call per case) before
+querying. Gated behind the `proptest-e2e` cargo feature — `mise run test:sqlx`
+enables it (CI has the secrets); a bare `cargo test` compiles it out. It is the
+**only** suite that can exercise "same plaintext, *different* ciphertext"
+(equality across independently-encrypted values), because the committed fixture
+corpus has no duplicate plaintexts. Integer scalars only for now (random `T`
+generation is trivial for integers).
+
+## The shared oracle engine
+
+`assert_eq_oracle` / `assert_ord_oracle` in
+[`../../../src/property.rs`](../../../src/property.rs) take a corpus of
+`(plaintext, payload_json)` rows and check, over every ordered pair, that:
+
+- `=` / `<>` on the `_eq` domain agree with plaintext `==` / `!=`, and
+- (ordered domains) `<` `<=` `>` `>=` and `ord_term` sort order agree with the
+  plaintext comparison.
+
+The fixture and e2e suites differ only in **where the rows come from**; the
+engine is identical.
+
+## Why ciphertext can't be `Arbitrary`-derived
+
+A valid payload's `hm`/`ob` terms are real ciphertext from `cipherstash-client`
+(`encrypt_eql`), which needs a live ZeroKMS handshake — there is no offline/mock
+cipher. `proptest` can only generate **plaintexts**; turning them into payloads
+means encrypting them. That is exactly why there are two integration suites: the
+fixture suite reuses already-encrypted values, and the e2e suite pays for fresh
+encryption to reach inputs the fixtures can't.
+
+## Conventions and footguns
+
+- **Never put these tests under a `scalars::` module.** `mise run test:matrix:inventory`
+  discovers scalar types from every `scalars::<X>::` test-name prefix, so a
+  `scalars::property::…` test would be mis-read as a scalar type and break the
+  catalog cross-check. They live under `property::` for this reason.
+- **The e2e suite is gated behind `proptest-e2e`.** Keep it that way so a
+  credential-less `cargo test` (and the lean crate path) still compiles.
+- **The e2e suite disables shrinking and failure persistence.** Every shrink
+  attempt would burn another ZeroKMS batch, ciphertext can't be meaningfully
+  shrunk, and fresh-each-run ciphertext can't be replayed.
+- **proptest + async bridge.** The `proptest!` body is sync; the DB-backed suites
+  run their async oracle on a per-case current-thread `tokio` runtime and connect
+  via `connect_pool()` (they cannot use `#[sqlx::test]`'s injected pool from a
+  sync body). Operator evaluation is read-only `SELECT`, so no per-test schema
+  isolation is needed.
+- **Equality-true must actually fire.** Random integer pairs almost never
+  collide, so the e2e corpus injects deliberate duplicate plaintexts (plus signed
+  extremes and zero) to exercise the `a == b ⇒ eq` branch across distinct
+  ciphertexts.
+
+## Running
+
+```bash
+# catalog suite only (no DB, no creds)
+cargo test -p eql-scalars proptest_invariants
+
+# fixture + edge-case suites (needs a prepared DB)
+mise run test:sqlx:prep
+cd tests/sqlx && cargo test --test encrypted_domain property::fixture_oracle property::edge_cases
+
+# all suites incl. e2e (needs DB + CS_* creds)
+mise run test:sqlx   # enables --features proptest-e2e
+```