refactor(eql): write the SQL source with schema and version placeholders

[coderdan]

Summary

EQL (Encrypt Query Language) is the SQL we install into a customer's Postgres so it can store and search encrypted values. ADR-0002 (#1139) decides that one SQL source should be installed under two names: eql_v3 for payloads written by cipherstash-client (the TypeScript SDK's engine) and eql_v4 for payloads written by Stack Encrypt. Postgres then refuses to compare a query of one with a column of the other, instead of silently returning no rows.

This PR is the first step: the SQL source stops naming its schemas and payload version literally, so it can be written out as either version. Nothing a customer installs changes. The v3 installer and uninstaller this branch builds are byte-identical to the ones main builds.

Changes

• SQL source: every file under packages/eql/src/v3, plus the version template, the search_path pin script and the uninstaller, writes {{prefix}} where it wrote eql_v3 (about 24k sites), and {{eql_version}} in the 90 domain CHECKs that compared VALUE->>'v' to '3'.
• eql-codegen: the generated SQL emits the same placeholders. The Rust bindings keep the literal eql_v3_ prefix, because they describe v3 payloads.
• eql-codegen render <3|4> <out> <file>...: new. It substitutes the placeholders, and refuses an unknown or unterminated placeholder and any literal eql_v3/eql_v4. A literal name would render the same for both versions, so the v4 bundle would quietly reach into v3.
• Build: tasks/build.sh renders the ordered surface into build/render/eql_v3/ (gitignored), runs the symbol-order and installer-completeness gates on the rendered files, and assembles release/ from them.
• Docs tooling: docs:validate:documented-sql runs psql over the rendered tree, and the Doxygen filter renders eql_v3 names, so the generated reference is unchanged.
• Docs: packages/eql/AGENTS.md gains a "Schema and version placeholders" section. The scalar-type reference shows extension SQL with placeholders.

Verification

• release/cipherstash-encrypt.sql, release/cipherstash-encrypt-uninstall.sql and src/deps-ordered-v3.txt: compared with cmp against a build of the base commit. All three are byte-identical.
• The placeholder rewrite cross-checks the generator: I rewrote the committed generated files mechanically, then regenerated them from the changed templates, and the generator's output matched the rewrite exactly.
• Passed: test:crates (eql-codegen 150 unit tests, including 8 new render tests), codegen:parity, types:check, typescript:check, test:schemas:parity, test:self_contained_v3, test:symbol_order_v3, test:symbol_order_selftest, test:installer_complete, test:build_ordering_helpers, test:doc-anchors, test:matrix:inventory, test:matrix:catalog-coverage, test:public_identifiers, release:prepare-bindings-assets.test, and root pnpm run test:scripts (71 files, 1296 tests).
• Not run locally: the SQLx suites, docs:validate:documented-sql, test:surface:snapshot, splinter and the clean-install smoke test. All need Postgres, and Docker wasn't running. test:docs_v3_grep also wasn't run, because it needs bash 4 and this Mac has bash 3. I edited its one source grep and checked that grep by hand. The installer is byte-identical, so the database suites see the same SQL; CI runs them.

Related

Refs #1141. Stacked on #1139 (the ADR). The next two PRs in the stack:

• The build also writes the eql_v4 bundle, with a gate that no eql_v3 name survives in it, and a test that an eql_v4 query term can't be compared with an eql_v3 column.
• The SQLx suites run against both installs.

Review notes

The 290 SQL files are a mechanical rewrite. Review crates/eql-codegen/src/render.rs, tasks/build.sh and the codegen const changes. The SQL diff is covered by the byte-identical check.

https://claude.ai/code/session_01CA4pFfaN4DPNSTLnJVNxsu

[changeset-bot]

⚠️ No Changeset found

Latest commit: 4edd586

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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