[3/6] feat: EQL v3 type checker driven by per-column domain capability

[freshtonic]

📚 eql-v3 PR  ·  3 of 6

Part of a queue. The PRs merge in FIFO order — the numbered order below, #1 first. Merging one supersedes the PRs after it until the author runs git queue sync (rebases the rest onto the merged base) and git queue submit (retargets their PRs).

✅🟢 #422 queue/eql-v3/setup-skills → main
✅🟢 #423 queue/eql-v3/upgrade-deps → queue/eql-v3/setup-skills
♻️🟢 #424 queue/eql-v3/typecheck → queue/eql-v3/upgrade-deps  👈 this PR
✅🟢 #428 queue/eql-v3/transform → queue/eql-v3/typecheck
✅🟢 #426 queue/eql-v3/showcase → queue/eql-v3/transform
⏳🟢 #427 queue/eql-v3/integration → queue/eql-v3/showcase

_{✅ approved · ♻️ changes requested · ⏳ review pending  |  🟣 merged · 🟢 open · ⚫ closed  —  status as of the last git queue submit.
🥞 Managed by git-queue — do not edit this list by hand.}

About this queue

Migrates CipherStash Proxy from EQL v2 to EQL v3 (cipherstash-client 0.34.1-alpha.4 → 0.42.0, EQL 2.3.0-pre.3 → 3.0.2), replacing the opaque eql_v2_encrypted composite type with 53 typed jsonb domains that encode both scalar type and searchable capability in the column type itself.

About this branch

Type checker for v3 domains — extends EQL Mapper to emit eql_v3_<token>_<capability> domains instead of eql_v2_encrypted
(designed, not yet built; the step that makes the migration actually work).

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 9d09c1c2-f763-4488-82f8-9fcd4d6f8a51

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch queue/eql-v3/typecheck

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[tobyhede]

Verified the v3 domain mapping against the actual eql-bindings 3.0.1 catalog: all nine term-key combinations it emits ([], ["hm"], ["op"], ["ob"], ["bf"], and the unions) map correctly, and storage-only eql_v3_json (Some(&[]) → none) is correctly distinguished from searchable eql_v3_json_search/_entry (None → JsonLike+Contain). The two bug fixes are correct and the regression tests encode the old buggy output as the discriminator — nice.

Findings, most substantive first.

1. eql_v3_json_entry is classified with inverted semantics. public.eql_v3_json_entry is in v3::all() and ste_vec_domain_type! leaves term_json_keys at the default None, so resolve("eql_v3_json_entry") returns JsonLike + Contain. But the installed SQL comments it as 'EQL encrypted JSONB leaf entry (equality, ordering)' — it's the -> result element, and its per-entry terms are hm XOR op. So a column of that type would type-check as supporting ->/@> and not =/<, which is backwards. No user declares such a column today, so it's latent, but every_public_column_domain_resolves_to_a_known_token_type actively asserts it resolves. Consider excluding the entry/document operand types from the column catalog rather than relying on nobody declaring them.

2. DomainIdentity::canonical collides with real domains that mean something else. canonical(Text, {json_like, ..}) takes the if traits.json_like { push("search") } branch and produces eql_v3_text_search — which is a real catalog domain whose terms are [hm, op, bf] (Eq+Ord+TokenMatch), not a JSON capability. This is live: notes (EQL: JsonLike + Contain) appears at eight sites in lib.rs tests plus type_env.rs:259. It can also emit genuinely non-catalog names (Eq+TokenMatch → eql_v3_text_eq_match, Contain → eql_v3_text_contain). The doc comment concedes it "is not guaranteed to equal the exact catalog typname" — worth strengthening that to "may collide with an unrelated real domain", or deriving the suffix so it can't produce a real-but-wrong name.

3. Test-fixture footgun from the new identity field. EqlValue derives PartialEq, so identity now participates in equality. Production is safe — both construction sites read traits and identity from the same ColumnKind::Eql on the same Column, so identity is a function of TableColumn and adds no discrimination (and EqlTerm::Partial's union applies to the bounds field, not EqlValue.2, so nothing desyncs). But fixtures can now disagree: a column declared with the explicit arm EQL("eql_v3_integer_ord"): Ord carries identity eql_v3_integer_ord, while an expected projection![(EQL(t.c: Ord))] builds the canonical eql_v3_text_ord — assert_eq! fails on a dimension the test wasn't testing. Loud rather than silent, but a papercut for whoever writes the transform tests next.

4. docs: is the wrong commit type. ~346 added lines are production Rust/SQL, including a new production dependency, a breaking public API change (ColumnKind::Eql gains a field, Column::eql gains an arg, ColumnKind loses Copy), a schema-loader rewrite, and a real behaviour fix (self.eq ^ other.eq → self.eq && !other.eq). The PR's own commits say feat/fix/refactor for three of seven. The body's "designed, not yet built" also undersells it. Matters for changelog generation and bisect.

5. v2 columns → native with only a warn! is right for a v3-only build, and it's not a plaintext-read exposure (a native passthrough returns the raw composite ciphertext). One caveat: eql_v2.to_encrypted does no validation and CREATE CAST (text AS eql_v2_encrypted) is AS ASSIGNMENT, so on the write path an explicitly-text-typed, JSON-parseable value ('42'::text) could be wrapped and stored in plaintext rather than erroring. Narrow, but it means "fails loudly" isn't quite airtight — worth making that warning hard to miss in ops.

6. No CHANGELOG entry — CLAUDE.md asks for one on user-facing changes. Not specific to this PR: none of #422/#423/#424/#426/#427/#428 touch CHANGELOG.md, while the queue collectively changes a public signature, swaps the v2 composite for v3 domains, and bumps cipherstash-client 0.34→0.42. Raising against the queue, not this branch.

[tobyhede]

Appears to be a working document.
Should this be committed?

[freshtonic]

@tobyhede I believe it should be - it's valuable context

[freshtonic]

Thanks for the thorough review — went through all six findings. Summary of what changed (all pushed):

1. eql_v3_json_entry classified with inverted semantics — Fixed. eql_v3_json_entry (the -> result element, SteVecEntry) is now excluded from the column-domain catalog via a NON_COLUMN_DOMAINS denylist, so resolve() returns None for it and a column mistakenly declared with that type falls through to a native column instead of JsonLike + Contain. The every_public_column_domain_resolves_to_a_known_token_type assertion skips the same list, and a new test pins that it no longer resolves while the real JSON column domains (eql_v3_json, eql_v3_json_search) still do. → fix(proxy): exclude eql_v3_json_entry from the column-domain catalog

2. DomainIdentity::canonical collides with real domains — Done (the doc route you suggested). The doc comment now states the synthesised name may collide with an unrelated real domain that means something else (with the canonical(Text, {json_like}) → eql_v3_text_search example), and that only from_domain_name is authoritative. → docs(eql-mapper): warn that DomainIdentity::canonical may collide with a real domain

3. Test-fixture footgun from the new identity field — Acknowledged, no change. It's loud-not-silent, as you note; leaving it as-is for whoever writes the transform tests next.

4. docs: is the wrong commit type — Not reworded. That's a message rewrite across the stack; leaving it for the merge rather than rebasing the whole queue for the type prefix.

5. v2 columns → native with only a warn! — Done. The warning now spells out that the column is served as a PLAINTEXT (native) column — Proxy runs no encrypt/decrypt on it, new writes are stored in plaintext, migrate before writing — instead of the softer "ignoring unsupported column". The deeper AS ASSIGNMENT write-path concern is inherent to having a v2 column on a v3 build (deliberately native+warn), so I made the warning impossible to miss rather than changing that behaviour. → feat(proxy): make the v2-column plaintext warning ops-visible

6. No CHANGELOG entry — Done (against the queue, per your framing). Added an [Unreleased] section covering the whole v3 migration; it lives on #428.