razeri_plugin_contract/

replication.rs

// Copyright (C) 2026 Gabriel Shea <gshea@ideapivot.com> - All Rights Reserved

//! Replication rendering traits with ANSI defaults.
//!
//! [`ReplicationRenderer`] extends [`SqlRenderer`] with methods for
//! SID (surrogate ID) function generation, data extraction, data loading, and
//! checksum validation. Each dialect crate overrides these methods to produce
//! platform-native SQL.
//!
//! ## Format names
//!
//! Methods that accept a `format` parameter use well-known string identifiers:
//!
//! | Name | Description |
//! |------|-------------|
//! | `"csv"` | Comma-separated values |
//! | `"parquet"` | Apache Parquet columnar format |
//! | `"json_lines"` | JSON Lines (one object per line) |
//! | `"native"` | Platform-native binary format |

use crate::SqlRenderer;

// ════════════════════════════════════════════════════════════════════════
// SID Prerequisites — the statement boundary
// ════════════════════════════════════════════════════════════════════════

/// **The line a dialect writes between two independently-executable statements
/// inside [`ReplicationRenderer::sid_prerequisites`].**
///
/// A prerequisite script is mostly prose — the `MariaDB` C source and the SQL
/// Server C# are emitted as comment blocks for an operator to compile — but two
/// arms emit real DDL a machine must run one statement at a time: Snowflake's
/// JavaScript UDF plus its SQL wrapper, and Databricks' Python UDF. Neither can
/// be recovered by splitting on `;`, because **both bodies contain
/// semicolons**: a JavaScript function body is nothing but semicolons.
///
/// So the boundary is declared rather than inferred. The delimiter is a SQL line
/// comment, so a script carrying it is still one paste-able file for a human
/// operator, and [`ReplicationRenderer::sid_prerequisite_statements`] is the one
/// splitter — a consumer that re-derived the boundary would be a second
/// definition of it, and a second definition is how the two drift apart.
///
/// **The inference-based sibling exists and is acknowledged here**:
/// `split_snowflake_sql` in
/// `integration-tests/tests/smoke/common/snowflake_fixture.rs` recovers
/// statements from arbitrary generated DDL by tracking `BEGIN`/`END` depth,
/// `$$` bodies and quoting — the only thing that *can* be done to a script
/// nobody declared a boundary in. It is not this, and neither replaces the
/// other: that one reads scripts razeri did not mark, this one reads the
/// prerequisite scripts razeri does. A future sweep that unifies them should
/// move the smoke fixture onto the declared boundary, not the other way round.
pub const SID_PREREQUISITE_STATEMENT_DELIMITER: &str =
    "-- ──── RAZERI SID PREREQUISITE STATEMENT ────";

/// **The input every generated prerequisite probe asks about.**
///
/// One word, and it is the one [`ReplicationRenderer::sid_validation_query`]
/// already puts in its `SELECT`. It lives here rather than in the bundle
/// generator because three producers must agree on it and they live in
/// different crates: the dialect writing the operator's instructions, the
/// generator writing the deploy script's comparison, and the validation query
/// itself. A probe that asked about one word while the instructions promised
/// another is a hand-spelled second variant — the shape that once shipped an
/// installer calling a function the engine does not have, with no test ever
/// running it.
pub const SID_PROBE_INPUT: &str = "test";

// ════════════════════════════════════════════════════════════════════════
// SID Prerequisites — what KIND of step this platform's is
// ════════════════════════════════════════════════════════════════════════

/// **What a platform's SID prerequisite actually asks of whoever deploys.**
///
/// The bundle's prerequisites step has to emit a different *shape* for each of
/// these, and the deploy script a different *behaviour*: one runs SQL, one
/// verifies and refuses, one refuses outright, one says there is nothing to do.
/// Sniffing that out of the prose at each call site would put the rule in the
/// generator, the script writer and the runner — three readings of one fact,
/// which is exactly how one derivation becomes two.
///
/// The default derives it from what the dialect already says, so a dialect that
/// overrides nothing is still classified correctly and only the one platform
/// the derivation cannot reach ([`SQLite`](Self::Refused)) has to override.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SidPrerequisiteKind {
    /// **Nothing to install: the engine's own hash already IS the canonical
    /// number** (XXH64 seed 0), reachable from SQL razeri emits.
    ///
    /// **A positive claim, and therefore never a default.** Saying this means
    /// razeri has *measured* that the platform's builtin returns XXH64 seed 0 —
    /// not that nobody has said otherwise. A dialect that has declared nothing
    /// gets [`Undeclared`](Self::Undeclared) instead, for the same reason
    /// `DdlRenderer::representable_timestamp_ceiling`'s `None` means *no
    /// measured ceiling* rather than *holds everything*.
    ///
    /// The derivation cannot reach this variant. A dialect claiming it
    /// **overrides [`ReplicationRenderer::sid_prerequisite_kind`] and cites the
    /// measurement**, which is what `ClickHouseDialect` does.
    None,

    /// Razeri emits statements that install it, and a deploy script can run
    /// them unattended: `INSTALL`/`LOAD` (`DuckDB`), `CREATE FUNCTION`
    /// (Snowflake's JavaScript UDF, Databricks' Python one).
    ///
    /// The test is *"can a script finish this with no human on the host"*. It is
    /// **not** "is the statement SQL": `CREATE EXTENSION` is SQL and only
    /// **registers** a shared object somebody compiled first, which is why
    /// `PostgreSQL` and Citus are [`OperatorArtifact`](Self::OperatorArtifact)
    /// and not this.
    SqlInstallable,

    /// An artifact the **operator** builds and places before any SQL can
    /// reference it — SQL Server's CLR assembly, `MariaDB`'s and `MySQL`'s
    /// `.so`, `PostgreSQL`'s and Citus's `pg_xxhash`. Razeri emits the source
    /// or the build recipe as prose; it cannot compile anything, and it will not
    /// pretend to.
    ///
    /// The deploy path's obligation here is the prerequisites verb: **verify,
    /// then
    /// refuse** — ask the engine for the function and stop in front of `schema`
    /// when it is not there, rather than deploying a warehouse whose keys it
    /// cannot compute.
    OperatorArtifact,

    /// The platform cannot be made to compute razeri's key from SQL **at all**,
    /// and no artifact an operator drops in changes that.
    ///
    /// `SQLite` is the case and, so far, the only one: a standalone `sqlite3`
    /// has no `CREATE FUNCTION` in its SQL surface, so there is no statement to
    /// emit and no library to load. Razeri-*driven* `SQLite` can register a
    /// function through `sqlite3_create_function()`, which is a C API, not SQL —
    /// so the bundle's razeri-free operator genuinely cannot get there from
    /// here.
    ///
    /// The answer is a **named refusal carried in the bundle**, checked before
    /// any data moves. Never a silent fall-back expression — and the fall-back is
    /// not hypothetical or historical: `SidSpelling`'s `sqlite` arm
    /// **still** renders `ABS(UNICODE(x))`, the code point of the input's first
    /// character. That is not a weak hash; it is not a hash.
    /// The refusal is what stops it reaching a warehouse; the expression itself
    /// is still what that arm would emit.
    Refused,

    /// **Nothing to install here, because razeri's own key function travels in
    /// `schema.sql` instead** — one definition per domain, created in the
    /// domain's own namespace.
    ///
    /// `BigQuery` is the case and the reason is name resolution, not taste: a
    /// bare `generate_sid('test')` is *"Function not found: `generate_sid`; Did
    /// you mean `generate_uuid`?"* there — no search path, no session schema, no
    /// default dataset inside a procedure body — so every call site must name
    /// the dataset the function was created in, and a prerequisites script has
    /// no dataset to create it in. The definition therefore rides `schema.sql`,
    /// where the domain's namespace is known.
    ///
    /// It is **not** [`None`](Self::None). That variant is the positive claim
    /// *"the engine's own hash IS the canonical number"*, which is false here:
    /// `BigQuery` has no XXH64 in any spelling and the key is a razeri-owned
    /// JavaScript UDF. What the two share is only the deploy behaviour —
    /// nothing to run before `schema.sql` — and sharing a behaviour is not
    /// sharing a claim.
    EmittedInSchema,

    /// **Razeri has no measured answer for this platform** — the honest default,
    /// and the one a dialect gets by saying nothing.
    ///
    /// # Why this variant exists
    ///
    /// Because the derivation used to answer [`None`](Self::None) here, turning
    /// *"this dialect declared nothing"* into the positive claim *"its own hash
    /// is razeri's number"*. Measured: the `agnostic` pseudo-dialect
    /// emitted a `prerequisites.sql` reading **"NOTHING TO INSTALL"** beside a
    /// `schema.sql` whose key helper calls `xxhash64(` — a portable *authoring*
    /// spelling that **no engine ships**. That is the `MySQL` defect
    /// (`MySqlDialect`'s empty `ReplicationRenderer` impl) reproduced by a
    /// second route, from the same asymmetry.
    ///
    /// # What it means to a deploy path
    ///
    /// The same as [`OperatorArtifact`](Self::OperatorArtifact): **verify, then
    /// refuse.** Safe-by-default is the only defensible reading of "razeri does
    /// not know" — the doctrine allows an emitted UDF or a named refusal and
    /// explicitly not a local approximation, and proceeding on an unmeasured
    /// platform is neither.
    ///
    /// A dialect that genuinely needs no prerequisite says so by overriding
    /// [`ReplicationRenderer::sid_prerequisite_kind`] to
    /// [`None`](Self::None), with its measurement cited.
    Undeclared,
}

/// **The executable statements inside a prerequisite script**, split on
/// [`SID_PREREQUISITE_STATEMENT_DELIMITER`].
///
/// The body of [`ReplicationRenderer::sid_prerequisite_statements`], lifted out
/// so a caller holding a script that is not `self.sid_prerequisites()` — the
/// bundle, when it swaps in
/// [`ReplicationRenderer::sid_pure_sql_fallback`] — splits it the same way
/// rather than growing a second reading of the boundary.
///
/// Leading comment and blank lines are dropped from each segment and one
/// trailing terminator is stripped; see the trait method for why both.
#[must_use]
pub fn statements_in_prerequisite_script(script: &str) -> Vec<String> {
    if !script.contains(SID_PREREQUISITE_STATEMENT_DELIMITER) {
        return Vec::new();
    }
    script
        .split(SID_PREREQUISITE_STATEMENT_DELIMITER)
        .filter_map(|segment| {
            let statement = segment
                .lines()
                .skip_while(|line| {
                    let line = line.trim_start();
                    line.is_empty() || line.starts_with("--")
                })
                .collect::<Vec<_>>()
                .join("\n");
            // One trailing terminator, not a run of them: `$$;` ends a body
            // whose own last character may be a `;` the statement needs.
            let statement = statement.trim_end().strip_suffix(';').map_or_else(
                || statement.trim_end().to_owned(),
                |trimmed| trimmed.trim_end().to_owned(),
            );
            (!statement.is_empty()).then_some(statement)
        })
        .collect()
}

/// **What shape a prerequisite script is**, read off the script itself.
///
/// The body of [`ReplicationRenderer::sid_prerequisite_kind`]'s default, lifted
/// out for the same reason as [`statements_in_prerequisite_script`]: a caller
/// classifying a script the dialect did not return from `sid_prerequisites()`
/// must reach the same three answers by the same rule. A second reading of the
/// table in the trait method's own doc comment is how a script comes to be
/// classified two ways.
///
/// The two answers this cannot reach — [`SidPrerequisiteKind::None`] and
/// [`SidPrerequisiteKind::Refused`] — are positive claims about an engine, and
/// a dialect makes them by overriding, never by writing a script this reads.
#[must_use]
pub fn kind_of_prerequisite_script(script: &str) -> SidPrerequisiteKind {
    if script.trim().is_empty() {
        SidPrerequisiteKind::Undeclared
    } else if statements_in_prerequisite_script(script).is_empty() {
        SidPrerequisiteKind::OperatorArtifact
    } else {
        SidPrerequisiteKind::SqlInstallable
    }
}

// ════════════════════════════════════════════════════════════════════════
// The external artifact that IS `generate_sid`
// ════════════════════════════════════════════════════════════════════════

/// **The identity of the artifact the bundle's prerequisites step installs as
/// `generate_sid`** — where one exists.
///
/// Returned by [`ReplicationRenderer::sid_external_artifact`], and the only
/// thing a dialect still has to say about the key function's *body*: on every
/// platform where razeri owns the name the body is
/// Razeri's one surrogate-key derivation and reads out of one table, so
/// there is nothing per-dialect left to declare.
///
/// # What this replaced — a producer nothing installs from only drifts
///
/// This was `SidFunctionSpec`, an enum with three arms. Two of them —
/// `SqlExpression` (the trait default, re-spelling the derivation over
/// `input_text`) and `ProceduralBlock` (`PostgresDialect`'s PL/pgSQL block) —
/// **lost their emitter** when the replication
/// precheck was pointed at the one envelope
/// (`razeri_sql::domain::scalar_function::generate_sid_helper`). Nothing
/// installed from them afterwards; only `razeri-materialize`'s census still
/// read them, which kept them from drifting but not from being dead. Retiring
/// them shrinks that census's producer count from four to three by an honest
/// count rather than by a quiet skip, and it took a live defect with it: on
/// `SQLite` the dead `SqlExpression` default was still reachable through the
/// bindings' `generate_sid_function_ddl`, where it rendered a `CREATE` around
/// `ABS(UNICODE(x))` — the code point of the input's first character, which is
/// not a hash — and around a parameter it did not declare.
///
/// The `input_text` convention died with those arms. `generate_sid`'s
/// parameter has **one** name, `input_value`, the envelope's.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SidExternalArtifact {
    /// Language name, e.g. `"tsql"`, `"C"`, `"javascript"`, `"python"`.
    pub language: String,
    /// Path or name of the external library, assembly, or emitted definition.
    pub object_file: String,
    /// Fully-qualified symbol within the library.
    pub link_symbol: String,
    /// Descriptive comment for the function — the **dialect's**, because *why
    /// the platform's built-in was refused* is a platform fact.
    pub comment: String,
}

// ════════════════════════════════════════════════════════════════════════
// ReplicationRenderer Trait
// ════════════════════════════════════════════════════════════════════════

/// Rendering methods for replication operations: SID generation, data
/// extraction, data loading, and checksum validation.
///
/// Defaults produce ANSI-safe SQL so extension dialects (e.g., `SQLite`) work
/// without implementing every method.
pub trait ReplicationRenderer: SqlRenderer {
    // ── SID (Surrogate ID) Generation ────────────────────────────────

    /// **Does an external artifact already carry the name `generate_sid` on
    /// this platform, and what is it?**
    ///
    /// `None` — the default, and the honest answer for most engines — means
    /// razeri itself defines the key function here: the body is
    /// Razeri's one surrogate-key derivation with the platform's own hash inlined,
    /// composed by
    /// `razeri_sql::domain::scalar_function::generate_sid_helper` from the
    /// platform name alone, so there is nothing for a dialect to spell.
    ///
    /// `Some(…)` names what the bundle's prerequisites step installs: SQL
    /// Server's CLR assembly, MySQL/MariaDB's C UDF, Snowflake's emitted
    /// JavaScript UDF, Databricks' emitted Python UDF. The derivation is inside
    /// the artifact rather than in any SQL razeri emits, so what razeri can
    /// still state — and what `razeri-materialize`'s census grades — is the
    /// artifact's *identity*, matched against the very prerequisites text that
    /// installs it.
    ///
    /// **This is not a body, and it never was one.** It used to be
    /// `sid_function_spec`, which could also answer with SQL razeri would then
    /// install; see [`SidExternalArtifact`] for what that cost and why the two
    /// expression-carrying arms are gone.
    ///
    /// A platform that can be given no function at all — `SQLite`,
    /// which has no `CREATE FUNCTION` in its SQL surface — answers `None`
    /// here too and says so through
    /// [`Self::sid_prerequisite_kind`] ([`SidPrerequisiteKind::Refused`]).
    ///
    /// **The two are read by two different readers, and the DDL builder is not
    /// the one that reads both.** `generate_sid_function_from_dialect`
    /// refuses on `!emits_key_helper(dialect) && sid_external_artifact().is_none()`
    /// — this method's `None` is the whole of its second condition, and it
    /// never consults the kind. What reads the **pair** is `razeri-materialize`'s
    /// census: where no artifact is declared and razeri emits no helper either,
    /// it requires the dialect to have said `Refused` out loud rather than
    /// having simply declared nothing, which is the distinction
    /// [`SidPrerequisiteKind::Undeclared`] exists to keep.
    fn sid_external_artifact(&self) -> Option<SidExternalArtifact> {
        None
    }

    /// Returns prerequisite SQL/instructions for SID deployment.
    ///
    /// For platforms that require extensions or external libraries (`PostgreSQL`
    /// `pg_xxhash`, SQL Server CLR, `MariaDB` C UDF), this returns the deployment
    /// script. Default: empty (no prerequisites needed).
    fn sid_prerequisites(&self) -> String {
        String::new()
    }

    /// **The executable statements inside [`Self::sid_prerequisites`], in
    /// order** — razeri's own text, split on razeri's own declared boundary.
    ///
    /// This exists so an equality-gate arm can *install what razeri emits*
    /// rather than a transcription of it — a hand-written copy in a test is a
    /// second implementation that drifts. The `MariaDB` arm already does this by hand
    /// for a C comment block; the two cloud arms need SQL statements, and a
    /// second splitter living in the test tree would be a second definition of
    /// the boundary.
    ///
    /// **A dialect that does not write
    /// [`SID_PREREQUISITE_STATEMENT_DELIMITER`] declares no executable
    /// statements**, and gets an empty vector. That is the honest answer for
    /// every arm whose prerequisite is an operator's compile step (SQL Server's
    /// CLR assembly, `MariaDB`'s and `MySQL`'s `.so`) and for the platforms with
    /// no prerequisite at all — it is *not* a promise that a caller can run the
    /// prose.
    ///
    /// Leading comment and blank lines are dropped from each segment, so the
    /// prose that explains a statement travels with it in the script and does
    /// not travel to the engine. Comments *inside* a statement survive: they are
    /// part of the statement the operator would paste.
    ///
    /// **The trailing terminator is dropped here, once.** A `;` is how the
    /// script reads to a human pasting the whole file, and is not part of a
    /// single statement over a REST statement API — Snowflake's and Databricks'
    /// both take exactly one. Stripping it in each consumer instead would put
    /// the same rule in the cloud arms *and* in the bundle executor, which
    /// is the shape this method exists to prevent. `sid_prerequisites()`' text
    /// is unchanged and keeps its semicolons.
    fn sid_prerequisite_statements(&self) -> Vec<String> {
        statements_in_prerequisite_script(&self.sid_prerequisites())
    }

    /// **A prerequisite script that installs the same key function without
    /// compiling anything** — where the platform has one, and `None` where it
    /// does not.
    ///
    /// The default is `None`: most platforms have exactly one prerequisite and
    /// [`Self::sid_prerequisites`] is it. A dialect answers `Some` only where
    /// **two honest routes to the same number** exist and the choice belongs to
    /// whoever deploys rather than to whoever designed — the case being a
    /// managed `PostgreSQL` service (`RDS`, Aurora, Cloud SQL), where nobody has
    /// a shell on the server host and so the compiled extension the ordinary
    /// step names can never be built.
    ///
    /// # What answering `Some` promises
    ///
    /// **The same number, byte for byte.** Not a near-enough hash and not a
    /// different algorithm: the surrogate-key law is one hash and one
    /// derivation everywhere, so a key minted through this route and a key
    /// minted through the compiled one are the same `BIGINT` and a warehouse can
    /// be moved between them without re-keying a row. A dialect that cannot
    /// promise that answers `None` and lets the ordinary step refuse.
    ///
    /// It is a **deploy-time** choice and nothing about it reaches a design: the
    /// text swaps into `prerequisites.sql` alone, `schema.sql` is unchanged, and
    /// every call site still calls the one public name.
    fn sid_pure_sql_fallback(&self) -> Option<String> {
        None
    }

    /// **Which of [`SidPrerequisiteKind`]'s shapes this platform's prerequisite
    /// is.**
    ///
    /// Derived from what the dialect already says, so the classification cannot
    /// drift from the text it classifies:
    ///
    /// | [`sid_prerequisites`](Self::sid_prerequisites) | [`sid_prerequisite_statements`](Self::sid_prerequisite_statements) | kind |
    /// |---|---|---|
    /// | empty | — | [`Undeclared`](SidPrerequisiteKind::Undeclared) |
    /// | prose **and** statements | non-empty | [`SqlInstallable`](SidPrerequisiteKind::SqlInstallable) |
    /// | prose only | empty | [`OperatorArtifact`](SidPrerequisiteKind::OperatorArtifact) |
    ///
    /// # Silence is `Undeclared`, never `None`
    ///
    /// The two answers the derivation **cannot** reach are the two that are
    /// *positive claims about an engine*:
    ///
    /// - [`None`](SidPrerequisiteKind::None) says the platform's own builtin
    ///   returns the canonical number. That is a measurement, not an absence, and
    ///   a dialect claiming it overrides this method and cites the arm that
    ///   measured it;
    /// - [`Refused`](SidPrerequisiteKind::Refused) says no SQL can ever install
    ///   the function here, which a platform with a native hash and a lazy
    ///   dialect author would also spell as silence.
    ///
    /// This derivation used to answer `None` for silence, and it was wrong twice
    /// over on real dialects: `MySqlDialect`'s empty `ReplicationRenderer` impl,
    /// and the `agnostic` pseudo-dialect whose emitted helper calls `xxhash64(`
    /// — a spelling no engine ships (measured, both through a
    /// generated bundle). It is the same asymmetry
    /// `DdlRenderer::representable_timestamp_ceiling` documents on its own
    /// `None`: *not measured* and *nothing to worry about* are opposite facts
    /// that read identically when a default supplies them.
    fn sid_prerequisite_kind(&self) -> SidPrerequisiteKind {
        kind_of_prerequisite_script(&self.sid_prerequisites())
    }

    /// Returns a validation query to verify the SID function is operational.
    ///
    /// Default: schema-qualified `SELECT generate_sid('test')`.
    fn sid_validation_query(&self, schema: Option<&str>, null_sid: i64) -> String {
        let qualified = match schema {
            Some(s) => format!("{s}.generate_sid"),
            None => "generate_sid".to_string(),
        };
        format!("SELECT {qualified}('test') AS test_sid, {null_sid} AS null_sid;\n")
    }

    // ── Data Extraction ──────────────────────────────────────────────

    /// Renders an extract/export SQL statement for the given table.
    ///
    /// The `format` parameter is one of: `"csv"`, `"parquet"`, `"json_lines"`, `"native"`.
    ///
    /// Default: ANSI `SELECT ... FROM ... WHERE ...` (no COPY).
    fn render_data_extract(
        &self,
        qualified: &str,
        columns: &str,
        file_path: &str,
        format: &str,
        where_clause: &str,
        _batch_size: Option<usize>,
    ) -> String {
        let _ = file_path;
        let _ = format;
        if where_clause.is_empty() {
            format!("SELECT {columns} FROM {qualified};\n")
        } else {
            format!("SELECT {columns} FROM {qualified} {where_clause};\n")
        }
    }

    // ── Data Loading ─────────────────────────────────────────────────

    /// Renders a load/import SQL statement for the given table.
    ///
    /// The `format` parameter is one of: `"csv"`, `"parquet"`, `"json_lines"`, `"native"`.
    ///
    /// Default: ANSI comment placeholder.
    fn render_data_load(&self, qualified: &str, file_path: &str, _format: &str) -> String {
        format!("-- COPY INTO {qualified} FROM '{file_path}';\n")
    }

    // ── Checksum / Validation ────────────────────────────────────────

    /// Renders a checksum validation query for data comparison.
    ///
    /// Default: `SELECT COUNT(*) AS cnt FROM <table>` (no checksum).
    fn render_checksum_query(&self, qualified: &str) -> String {
        format!("SELECT COUNT(*) AS cnt FROM {qualified};\n")
    }

    // ── Platform Warnings ────────────────────────────────────────────

    /// Warning about Parquet export limitations on this platform.
    ///
    /// Default: `None` (no warning needed).
    fn parquet_export_warning(&self) -> Option<&str> {
        None
    }

    /// Warning about SID function deployment requirements on this platform.
    ///
    /// Default: `None` (no special deployment needed).
    fn sid_deployment_warning(&self) -> Option<&str> {
        None
    }

    /// General replication caveats for this platform as a target.
    ///
    /// Default: empty (no platform-specific caveats).
    fn replication_target_warnings(&self) -> Vec<String> {
        Vec::new()
    }

    /// Warning about TRUNCATE behavior on this platform.
    ///
    /// Default: `None` (TRUNCATE works normally).
    fn truncate_caveat(&self) -> Option<&str> {
        None
    }
}

#[cfg(test)]
mod tests {
    use super::{ReplicationRenderer, SID_PREREQUISITE_STATEMENT_DELIMITER};
    use crate::agnostic::AnsiDialect;

    /// A dialect whose prerequisites are whatever a test hands it.
    struct Emitting(String);

    impl crate::SqlRenderer for Emitting {
        fn dialect_name(&self) -> &'static str {
            "emitting"
        }
        fn render_data_type(&self, dt: &crate::DataType) -> String {
            AnsiDialect.render_data_type(dt)
        }
        fn quote_identifier(&self, name: &str) -> String {
            AnsiDialect.quote_identifier(name)
        }
        fn qualify_name(&self, schema: Option<&str>, name: &str) -> String {
            AnsiDialect.qualify_name(schema, name)
        }
        fn render_current_timestamp(&self) -> String {
            AnsiDialect.render_current_timestamp()
        }
    }
    impl crate::DdlRenderer for Emitting {}
    impl crate::FormulaRenderer for Emitting {}
    impl ReplicationRenderer for Emitting {
        fn sid_prerequisites(&self) -> String {
            self.0.clone()
        }
    }

    /// **A JavaScript body is nothing but semicolons**, which is exactly why the
    /// boundary is declared instead of inferred. Splitting the text below on
    /// `;` yields five fragments, none of them a statement.
    #[test]
    fn the_delimiter_recovers_statements_a_semicolon_split_would_fracture() {
        let script = format!(
            "-- prose the operator reads\n\
             {SID_PREREQUISITE_STATEMENT_DELIMITER}\n\
             -- why this one exists\n\
             CREATE FUNCTION f() AS $$\n  var a = 1; var b = 2; return a + b;\n$$;\n\
             {SID_PREREQUISITE_STATEMENT_DELIMITER}\n\
             CREATE FUNCTION g() AS $$ 1 $$;\n"
        );
        let statements = Emitting(script).sid_prerequisite_statements();
        assert_eq!(statements.len(), 2, "{statements:#?}");
        assert!(statements[0].starts_with("CREATE FUNCTION f()"), "{:?}", statements[0]);
        assert!(statements[0].contains("var a = 1; var b = 2; return a + b;"));
        assert_eq!(statements[1], "CREATE FUNCTION g() AS $$ 1 $$");
    }

    /// **The trailing terminator is dropped exactly once, and only at the end.**
    ///
    /// A REST statement API takes one statement and no terminator; a human
    /// pasting the script wants the `;`. Both are served by leaving it in
    /// `sid_prerequisites()`' text and removing it here — once, so a body whose
    /// own last character is a `;` (every JavaScript function) keeps it.
    #[test]
    fn one_trailing_terminator_is_dropped_and_the_bodys_own_semicolons_survive() {
        let script = format!(
            "{SID_PREREQUISITE_STATEMENT_DELIMITER}\n\
             CREATE FUNCTION f() AS $$\n  return 1;\n$$;\n\
             {SID_PREREQUISITE_STATEMENT_DELIMITER}\n\
             CREATE FUNCTION g() AS $$ 1 $$\n"
        );
        let statements = Emitting(script).sid_prerequisite_statements();
        assert_eq!(statements[0], "CREATE FUNCTION f() AS $$\n  return 1;\n$$");
        assert!(statements[0].contains("return 1;"), "the body's own `;` is not a terminator");
        assert_eq!(
            statements[1], "CREATE FUNCTION g() AS $$ 1 $$",
            "a statement with no terminator is unchanged"
        );
    }

    /// **No delimiter means no executable statements, and that is an answer.**
    /// The prerequisite scripts for SQL Server, `MySQL` and `MariaDB` are an
    /// operator's compile recipe wrapped in comments; handing a caller the prose
    /// as if it were DDL is how a deferral turns into a failure nobody can read.
    #[test]
    fn an_undelimited_script_declares_no_executable_statements() {
        let operator_recipe = "-- compile this yourself:\n/* int main() { } */\n".to_owned();
        assert!(Emitting(operator_recipe).sid_prerequisite_statements().is_empty());
        assert!(AnsiDialect.sid_prerequisite_statements().is_empty());
    }
}