docs(development): eql_v2↔eql_v3 comparison + v3 implementation audit

[tobyhede]

What

Adds two internal engineering reference documents under docs/development/:

• eql-v2-vs-v3-comparison.md — comparative audit / gap analysis of the (now-removed) eql_v2 surface vs the eql_v3 encrypted-domain surface.
• eql-v3-implementation-audit.md — v3-only deep-dive companion.

Placed under docs/development/ (not docs/reference/) because both legitimately discuss the removed eql_v2 surface, which the docs_v3_grep CI gate forbids in user-facing docs — docs/development/ is an excluded internal-docs subtree.

Verification notes

eql_v2 was removed from the tree in 3.0.0, so its file:line citations are no longer resolvable against the working tree. The comparison doc verifies them against git history instead:

• v2 SQL surface → 462b020c^ (parent of "feat!: remove eql_v2 SQL surface")
• v2 test files → 40d35e8c^ (deleted in a separate commit)
• eql_v3 citations → current tree

All claims were re-verified 2026-06-24 via parallel sub-audits. Notable corrections folded in:

• Test counts re-derived authoritatively. cargo test -- --list (compiled + macro-expanded, no DB) → 2,547 runnable tests (2,256 in the encrypted_domain binary). v2 baseline ≈ 407 hand-written #[sqlx::test] cases at 40d35e8c^. The doc distinguishes harness-listed vs fork-reproducible source-grep counts.
• Citations to the gitignored generated scalar SQL (*_types.sql) repointed to the committed codegen goldens (tests/codegen/reference/…) and templates (crates/eql-codegen/templates/…) so every claim is checkable.
• Stale items fixed: Port configuration (config + encryptindex) functions to eql_v3 #312 closed not planned (config/encryptindex decided client-side), eql_v3.version() now ships, corrected line numbers for the ORE <= 16 guard and the v3 pin-search-path structural rule.

Type

Docs-only. No code or behaviour change; no CHANGELOG entry required. Base: eql_v3.

Draft for review.

[coderabbitai]

Important

Review skipped

Draft detected.

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

Run ID: bfd8b9b3-37f5-457e-ba79-5231d191b177

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 docs/eql-v2-v3-comparison-audit

---

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.}