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

packages/eql/.gitattributes

@@ -8,6 +8,8 @@
 #     and drift-gated by `mise run codegen:parity`. (The hand-written
 #     src/v3/scalars/functions.sql and *_extensions.sql are NOT generated and
 #     are deliberately left unmarked.)
+#   - src/v3/scalars/ore_fallback.sql : the one generated file directly under
+#     src/v3/scalars, outside the per-type directories the globs above match.
 #   - tests/sqlx/snapshots/*_expanded.rs : `cargo expand` snapshots of the
 #     scalar matrix macros (the start_line/end_line churn is location drift).
 #   - tests/sqlx/snapshots/matrix_tests*.txt : matrix-coverage inventory pinned
@@ -19,6 +21,7 @@ src/v3/scalars/*/*_types.sql linguist-generated
 src/v3/scalars/*/*_functions.sql linguist-generated
 src/v3/scalars/*/*_operators.sql linguist-generated
 src/v3/scalars/*/*_aggregates.sql linguist-generated
+src/v3/scalars/ore_fallback.sql linguist-generated
 tests/sqlx/snapshots/*_expanded.rs linguist-generated
 tests/sqlx/snapshots/matrix_tests*.txt linguist-generated
 

packages/eql/.gitignore

@@ -260,3 +260,7 @@ nextest.tar.zst
 docs/decisions/2026-06-10-eql-v3-json-type-kind.md
 docs/handoff/2026-06-10-v3-jsonb-fixture-alignment.md
 .claude/
+
+# Rendered SQL per EQL version, written by tasks/build.sh from the placeholder
+# source (ADR-0002). Anchored: tasks/build/ is tracked.
+/build/

packages/eql/AGENTS.md

@@ -42,6 +42,21 @@ This project uses `mise` for task management. Common commands:
   - `cipherstash-encrypt.sql` - The sole installer: the self-contained `eql_v3` surface, globbed from `src/v3` only (no `eql_v2`; installable into a DB with no `eql_v2` present)
   - `cipherstash-encrypt-uninstall.sql` - Matching uninstaller
 
+#### Schema and version placeholders
+
+The SQL source never names its schemas or its payload version literally. It writes two placeholders, and the build renders the one source once per EQL version (ADR-0002, `docs/adr/0002-*` at the repo root):
+
+| placeholder | rendered for `eql_v3` | rendered for `eql_v4` |
+|---|---|---|
+| `{{prefix}}` | `eql_v3` | `eql_v4` |
+| `{{eql_version}}` | `3` | `4` |
+
+`{{prefix}}` is the schema and the start of every other name: `{{prefix}}.eq_term`, `{{prefix}}_internal.hmac_256`, `public.{{prefix}}_text_eq`. `{{eql_version}}` appears in every domain CHECK: `VALUE->>'v' = '{{eql_version}}'`. This covers every file under `src/v3/` (hand-written and generated), `src/v3/version.template`, `tasks/pin_search_path_v3.sql` and `tasks/uninstall-v3.sql`. The generator emits the placeholders too: `SCHEMA`, `INTERNAL_SCHEMA`, `PUBLIC_TYPNAME_PREFIX` and `EQL_VERSION` in `crates/eql-codegen/src/consts.rs` are placeholder strings. The Rust bindings are the exception. They describe v3 payloads and keep `eql_domains::PUBLIC_TYPNAME_PREFIX`, the literal `eql_v3_`.
+
+`tasks/build.sh` renders the ordered source into `build/render/eql_v3/` (gitignored, same relative paths) with `eql-codegen render`, runs the symbol-order and installer-completeness gates on the rendered files, and assembles `release/` from them. The renderer refuses three things: an unknown placeholder, an unterminated `{{`, and a **literal `eql_v3` or `eql_v4`** anywhere in the source, comments included. A literal name renders identically for both versions, so the v4 bundle would reach into v3. Write the placeholder in prose too.
+
+Anything that needs the source as real SQL reads the rendered tree, not `src/`: `docs:validate:documented-sql` runs psql over `build/render/eql_v3/src`, and the Doxygen input filter (`tasks/docs/doxygen-filter.sh`) renders `eql_v3` names on the fly. A new tool that parses `src/v3` must do one or the other.
+
 There are no longer separate Main / Supabase / Protect / v3-only build variants. The combined `eql_v2` build that previously produced multiple artefacts has been removed; the v3 surface now ships as one self-contained installer under the canonical `cipherstash-encrypt.sql` name (`eql-codegen order` walks `src/v3` only). Because the surface owns no `eql_v2` dependency, it is already Supabase / managed-Postgres compatible (functional indexes over extractors, no superuser-only operator classes) without a dedicated subset build. Self-containment — no `-- REQUIRE:` edge pointing outside `src/v3`, no `eql_v2.<symbol>` anywhere in the surface — is enforced at build time by `surface_order`'s `OutsideSurface` error (`crates/eql-codegen/src/ordering.rs`) and CI-gated by `mise run test:self_contained_v3`.
 
 ## Project Architecture

packages/eql/crates/eql-codegen/src/bindings.rs

@@ -83,6 +83,13 @@ fn capability_label(domain_name: &str) -> &'static str {
     }
 }
 
+/// The schema-qualified `eql_v3` domain a payload struct binds, e.g.
+/// `public.eql_v3_integer_eq`. The bindings describe v3 payloads only, so they
+/// name it literally, where the SQL surface writes the `{{prefix}}` placeholder.
+fn v3_domain_name(full: &str) -> String {
+    format!("public.{}{full}", eql_domains::PUBLIC_TYPNAME_PREFIX)
+}
+
 /// Render the catalog-derived struct doc lines for a domain: a summary line
 /// (`` `public.<name>` — <label>. ``) and a detail line listing the supported
 /// SQL operators and the required payload keys. Every part is derived from data
@@ -98,7 +105,7 @@ fn struct_doc_lines(full: &str, domain: &Domain) -> [String; 3] {
     // single leading space, so JSON Schema `description` is unaffected.
     let summary = format!(
         " `{}` — {}.",
-        crate::context::domain_name(full),
+        v3_domain_name(full),
         capability_label(domain.name)
     );
 
@@ -162,7 +169,7 @@ fn reference_docs(family: &DomainFamily) -> TokenStream {
 fn render_struct(family: &DomainFamily, domain: &Domain) -> TokenStream {
     let full = domain.full_name(family.name);
     let ident = format_ident!("{}", domain.struct_ident(family.name));
-    let sql_domain = crate::context::domain_name(&full);
+    let sql_domain = v3_domain_name(&full);
     let [doc_summary, doc_blank, doc_detail] = struct_doc_lines(&full, domain);
     let reference = reference_docs(family);
     let (encryption, version, context) = encryption_attrs(family, domain, false);
@@ -604,7 +611,7 @@ pub fn render_payload_rs() -> String {
         let module = format_ident!("{}", f.name);
         let strukt = format_ident!("{}", d.rust_struct_name(f.name));
         let full = d.full_name(f.name);
-        let doc = format!(" The `{}` payload.", crate::context::domain_name(&full));
+        let doc = format!(" The `{}` payload.", v3_domain_name(&full));
         variants.extend(quote! {
             #[doc = #doc]
             #strukt(super::#module::#strukt),

packages/eql/crates/eql-codegen/src/consts.rs

@@ -14,15 +14,19 @@ pub(crate) const AUTO_GENERATED_MARKER: &str = "-- AUTOMATICALLY GENERATED FILE.
 pub(crate) const RUST_GENERATED_MARKER: &str =
     "// @generated by eql-codegen from the eql-domains catalog — do not edit";
 
-/// The public `eql_v3` API surface: query operators, index extractors,
+/// The generated SQL names its schemas and payload version by placeholder,
+/// never literally: [`crate::render`] writes the one source out as `eql_v3`
+/// (version 3) and `eql_v4` (version 4). See ADR-0002.
+///
+/// The public API schema (`eql_v3` once rendered): query operators, index extractors,
 /// aggregates, AND the operator-backing comparison **wrappers**
 /// (`eq`/`neq`/`lt`/`lte`/`gt`/`gte`/`contains`/`contained_by`). The wrappers
 /// are public because they are the function-form equivalent of every supported
 /// operator — required on platforms without operator support (Supabase/PostgREST
 /// calls functions, not operators). User-column encrypted domains live in
 /// `public`; only index-term TYPES and never-invoked plumbing live in
 /// `INTERNAL_SCHEMA`.
-pub(crate) const SCHEMA: &str = "eql_v3";
+pub(crate) const SCHEMA: &str = "{{prefix}}";
 
 /// The schema housing INTERNAL eql_v3 objects only: the SEM index-term types
 /// (`hmac_256`, `bloom_filter`, `ore_block_256(_term)`, `ope_cllw`) and their
@@ -33,7 +37,16 @@ pub(crate) const SCHEMA: &str = "eql_v3";
 /// picker. NOTE: the operator-backing comparison *wrappers* are NOT here —
 /// they are public in `SCHEMA` (see above) so every operator has a callable
 /// function equivalent.
-pub(crate) const INTERNAL_SCHEMA: &str = "eql_v3_internal";
+pub(crate) const INTERNAL_SCHEMA: &str = "{{prefix}}_internal";
+
+/// The bare typname prefix of every public-schema encrypted domain, e.g. the
+/// `{{prefix}}_` of `public.{{prefix}}_integer_eq`. The SQL counterpart of
+/// [`eql_domains::PUBLIC_TYPNAME_PREFIX`], which stays the literal `eql_v3_`
+/// for the Rust bindings: those describe v3 payloads only.
+pub(crate) const PUBLIC_TYPNAME_PREFIX: &str = "{{prefix}}_";
+
+/// The payload version every domain CHECK compares `VALUE->>'v'` against.
+pub(crate) const EQL_VERSION: &str = "{{eql_version}}";
 
 /// Always-present payload keys checked for presence in every domain CHECK.
 /// Term-specific keys are appended after these by `context::domain_block`.
@@ -69,8 +82,8 @@ mod tests {
         // `list-schemas` subcommand) so a hand-edit to one side without the
         // other fails CI. Pinning the values here catches a Rust-side rename
         // before the SQL is even consulted.
-        assert_eq!(SCHEMA, "eql_v3");
-        assert_eq!(INTERNAL_SCHEMA, "eql_v3_internal");
+        assert_eq!(SCHEMA, "{{prefix}}");
+        assert_eq!(INTERNAL_SCHEMA, "{{prefix}}_internal");
         // `owned_schemas()` (lib.rs) is the public accessor the binary prints;
         // it must derive from these consts, public first.
         assert_eq!(crate::owned_schemas(), [SCHEMA, INTERNAL_SCHEMA]);

packages/eql/crates/eql-codegen/src/context.rs

@@ -61,6 +61,7 @@ pub fn environment() -> minijinja::Environment<'static> {
     .expect("ore_fallback.sql template");
     env.add_global("schema", SCHEMA);
     env.add_global("internal_schema", INTERNAL_SCHEMA);
+    env.add_global("eql_version", EQL_VERSION);
     env
 }
 
@@ -390,15 +391,15 @@ pub struct OreFallbackEntry {
 }
 
 /// The bare pg_type typname of a public-schema encrypted domain: the catalog
-/// name carrying the [`eql_domains::PUBLIC_TYPNAME_PREFIX`] version prefix,
-/// e.g. `eql_v3_integer_eq`. The prefix keeps EQL domains from
+/// name carrying the [`PUBLIC_TYPNAME_PREFIX`] version prefix,
+/// e.g. `{{prefix}}_integer_eq` (`eql_v3_integer_eq` once rendered). The prefix keeps EQL domains from
 /// shadowing PostgreSQL built-in type names (`integer`, `text`, `json`, …)
 /// and gives each EQL version a distinct column-type namespace so multiple
 /// versions can coexist in one database. Catalog names stay bare — the prefix
 /// is applied only at SQL-name construction (file names, REQUIRE paths,
 /// struct idents, and test names all keep the bare name).
 pub fn public_typname(name: &str) -> String {
-    format!("{}{name}", eql_domains::PUBLIC_TYPNAME_PREFIX)
+    format!("{PUBLIC_TYPNAME_PREFIX}{name}")
 }
 
 /// The schema-qualified SQL domain type name, e.g. `public.eql_v3_integer_eq`.
@@ -463,13 +464,13 @@ mod tests {
 
     #[test]
     fn domain_name_qualifies_user_domains_with_public_schema() {
-        assert_eq!(domain_name("integer_eq"), "public.eql_v3_integer_eq");
+        assert_eq!(domain_name("integer_eq"), "public.{{prefix}}_integer_eq");
     }
 
     #[test]
     fn public_typname_carries_version_prefix() {
-        assert_eq!(public_typname("integer"), "eql_v3_integer");
-        assert_eq!(public_typname("text_match"), "eql_v3_text_match");
+        assert_eq!(public_typname("integer"), "{{prefix}}_integer");
+        assert_eq!(public_typname("text_match"), "{{prefix}}_text_match");
     }
 
     #[test]

packages/eql/crates/eql-codegen/src/generate.rs

@@ -1150,6 +1150,65 @@ mod tests {
             .expect("domain name")
     }
 
+    // The renderers emit placeholder SQL. These shadow them, rendering their
+    // output as eql_v3, so the assertions below read as installed SQL and every
+    // rendered file is also checked to be free of literal names and unknown
+    // placeholders.
+    fn v3(sql: String) -> String {
+        crate::render::render_str(&sql, crate::render::EqlVersion::V3).expect("renders as eql_v3")
+    }
+
+    fn render_types_file(spec: &DomainFamily) -> String {
+        v3(super::render_types_file(spec))
+    }
+
+    fn render_functions_file(family_name: &str, domain: &Domain) -> String {
+        v3(super::render_functions_file(family_name, domain))
+    }
+
+    fn render_operators_file(family_name: &str, domain: &Domain) -> String {
+        v3(super::render_operators_file(family_name, domain))
+    }
+
+    fn render_aggregates_file(family_name: &str, domain: &Domain) -> Option<String> {
+        super::render_aggregates_file(family_name, domain).map(v3)
+    }
+
+    fn render_ore_fallback_file() -> String {
+        v3(super::render_ore_fallback_file())
+    }
+
+    fn render_json_entry_cross_functions(
+        spec: &DomainFamily,
+        domains: &[&Domain],
+        blocked_domains: &[&Domain],
+    ) -> String {
+        v3(super::render_json_entry_cross_functions(
+            spec,
+            domains,
+            blocked_domains,
+        ))
+    }
+
+    fn render_json_entry_cross_operators(
+        spec: &DomainFamily,
+        domains: &[&Domain],
+        blocked_domains: &[&Domain],
+    ) -> String {
+        v3(super::render_json_entry_cross_operators(
+            spec,
+            domains,
+            blocked_domains,
+        ))
+    }
+
+    fn render_type(spec: &DomainFamily, out_dir: &Path) -> Vec<(PathBuf, String)> {
+        super::render_type(spec, out_dir)
+            .into_iter()
+            .map(|(p, sql)| (p, v3(sql)))
+            .collect()
+    }
+
     use std::fs;
 
     #[test]
@@ -1873,8 +1932,8 @@ mod tests {
                 shape: Shape::Scalar,
             },
         );
-        assert_eq!(block.typname, "eql_v3_integer_q"); // no quote present → unchanged
-                                                       // keys are sql_str-escaped key tokens; none should carry a bare unescaped quote.
+        assert_eq!(block.typname, "{{prefix}}_integer_q"); // no quote present → unchanged
+                                                           // keys are sql_str-escaped key tokens; none should carry a bare unescaped quote.
         assert!(block.keys.iter().all(|k| !k.contains("o'")));
     }
 
@@ -2169,7 +2228,7 @@ mod tests {
     fn json_entry_type_is_derived_from_the_catalog() {
         // Not a hardcoded literal: a catalog rename or PUBLIC_TYPNAME_PREFIX bump
         // must flow through rather than silently drift (cf. #398 jsonb -> json).
-        assert_eq!(json_entry_type(), "public.eql_v3_json_entry");
+        assert_eq!(json_entry_type(), "public.{{prefix}}_json_entry");
         assert_eq!(json_entry_stem("integer"), "json_entry_integer");
         assert_eq!(
             json_entry_functions_path("integer"),

packages/eql/crates/eql-codegen/src/lib.rs

@@ -15,6 +15,7 @@ pub mod generate;
 pub mod go_eql;
 pub mod operator_surface;
 pub mod ordering;
+pub mod render;
 pub mod targets;
 pub mod writer;
 

packages/eql/crates/eql-codegen/src/main.rs

@@ -117,6 +117,33 @@ fn main() -> ExitCode {
         }
     }
 
+    // `render <3|4> <out-dir> <file>...`: write each placeholder source file
+    // (relative to the working directory) as that EQL version, to the same
+    // relative path under <out-dir>. Consumed by tasks/build.sh, which renders
+    // the ordered surface and assembles the installer from the result.
+    if args.len() >= 4 && args[1] == "render" {
+        let version = match args[2].parse::<eql_codegen::render::EqlVersion>() {
+            Ok(v) => v,
+            Err(e) => {
+                eprintln!("error: {e}");
+                return ExitCode::from(2);
+            }
+        };
+        let files: Vec<PathBuf> = args[4..].iter().map(PathBuf::from).collect();
+        return match eql_codegen::render::render_files(
+            std::path::Path::new("."),
+            &files,
+            std::path::Path::new(&args[3]),
+            version,
+        ) {
+            Ok(()) => ExitCode::SUCCESS,
+            Err(e) => {
+                eprintln!("error: {e}");
+                ExitCode::FAILURE
+            }
+        };
+    }
+
     // `clean`: remove the generated SQL surface (marker-aware) under every
     // src/v3/scalars/* type dir. Replaces build.sh's filename-pattern sweep;
     // hand-written files (no AUTO-GENERATED marker) are preserved.
@@ -152,6 +179,7 @@ fn main() -> ExitCode {
     eprintln!("Usage: eql-codegen            (generate all types)");
     eprintln!("       eql-codegen order      (print the src/v3 install order, one path per line)");
     eprintln!("       eql-codegen clean      (remove the generated SQL surface)");
+    eprintln!("       eql-codegen render <3|4> <out-dir> <file>... (render placeholder SQL as one EQL version)");
     eprintln!("       eql-codegen list-types (print catalog tokens)");
     eprintln!("       eql-codegen list-schemas (print owned schemas, public first)");
     eprintln!("       eql-codegen dump-catalog (print catalog surface as JSON)");