razeri-plugin-contract 0.1.0

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

//! **How this engine spells a surrogate key** — the one thing about the key a
//! dialect decides.
//!
//! Razeri derives every surrogate key one way:
//!
//! ```text
//! guard( hash( normalize(part₁) ‖ '|' ‖ … ‖ normalize(partₙ) ) )
//! ```
//!
//! That derivation is Razeri's and is composed in one place. What varies
//! between engines is only the **vocabulary** — what this engine calls `LOWER`,
//! what it calls `TRIM`, how it joins strings, how it casts a value to text,
//! and how it spells a 64-bit hash. [`SidSpelling`] is that vocabulary, and a
//! dialect states it by overriding
//! [`SqlRenderer::sid_spelling`](crate::SqlRenderer::sid_spelling).
//!
//! Two expressions built from this struct differ **only** in these fields,
//! which is what makes *"provably the same key on every engine"* a proof
//! rather than an assumption.
//!
//! # If your engine has no 64-bit hash
//!
//! Say so rather than reaching for the nearest-looking function. A hash that is
//! deterministic *within* one warehouse and equal to nothing outside it is the
//! exact lock-in a portable key exists to end — a warehouse keyed with it
//! reconciles against nothing. The honest answers are an artifact your dialect
//! installs (name it in [`SidSpelling::hash`] and emit its definition from your
//! prerequisites), or a refusal that says what the reader should do instead.

/// The [`SidSpelling::platform`] of a dialect that has not stated its spelling.
///
/// The default [`SidSpelling`] is ANSI's vocabulary, which is a **guess** and
/// not a claim about any platform. It has to exist — a dialect must render
/// *something* — and it has to be distinguishable from the agnostic renderer's
/// answer, which is ANSI on purpose. Otherwise an unspelled platform gets ANSI
/// everywhere, every producer agrees, and Razeri's census goes green over a
/// platform nobody has spelled: a gate that cannot see its own blind spot.
///
/// **A dialect that leaves this value in place is telling Razeri it has not
/// decided**, and the conformance kit reports it as an unanswered obligation.
pub const UNKNOWN_PLATFORM: &str = "unknown";

/// How a dialect spells `LOWER`.
///
/// The canonical lowercase is fixed as **locale-independent simple case
/// mapping, one code point to one code point, with no combining mark
/// introduced by the operation**. Some engines' `LOWER` is exactly that;
/// [`Lower::SimpleFoldViaReplace`] is for the ones whose `LOWER` is the
/// **full** mapping instead, which is measurably a different function.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Lower {
    /// `LOWER(x)`, in the platform's own casing. Measured against the canonical
    /// reference on `DuckDB`, `PostgreSQL`, Citus and `MariaDB`: all four fold
    /// `İ` (U+0130) to a bare `i` and lower the rest of the BMP, which is the
    /// canonical mapping.
    Function(&'static str),
    /// `<lower>(<replace>(<replace>(x, 'İ', 'I'), 'Σ', 'σ'))` — the
    /// **full**-fold engines, whose Unicode-aware lowercase is a different
    /// function from the canonical simple case mapping on two code points, for
    /// **two different reasons**. The reasons do not merge, and stating them as
    /// one would round the evidence up:
    ///
    /// - **`İ` (U+0130) — the unconditional divergence.** Its full lowercase is
    ///   `i` + U+0307, a combining mark the canonical mapping excludes by name,
    ///   and it is the **only** code point whose simple and full mappings
    ///   differ with no context at all. Replacing it with `I` first makes the
    ///   composition exactly the simple mapping;
    /// - **`Σ` (U+03A3) — the conditional divergence.** Its full lowercase is
    ///   `σ` *except* word-finally, where Unicode's `Final_Sigma` condition
    ///   makes it `ς` (U+03C2). No enumeration of unconditional mappings can
    ///   see this, which is exactly why the İ fix's exhaustive proof did not
    ///   cover it: a different quantifier hides a different letter. Replacing
    ///   every `Σ` with an already-lowercase `σ` first removes the context the
    ///   rule reads, and `LOWER` then leaves it alone.
    ///
    /// With both applied the composition is the simple mapping over the whole
    /// scalar space — an exact rendering of the canonical clause in the
    /// platform's own vocabulary, never a local approximation. The reason this
    /// is one variant rather than a per-platform arm is that the *reasoning* is
    /// one reasoning; only the two function names differ.
    ///
    /// **Three engines have been measured needing it** — `ClickHouse`
    /// (`lowerUTF8` / `replaceAll`), Snowflake (`LOWER` / `REPLACE`) and
    /// Databricks (`LOWER` / `REPLACE`) — and every one of the three was found
    /// by *executing* a Turkish and a Greek probe, never by reading a manual.
    /// If you have not run those two probes on your engine, you do not yet know
    /// which variant is yours.
    SimpleFoldViaReplace {
        /// The platform's full-fold lowercase function.
        lower: &'static str,
        /// The platform's three-argument string-replacement function.
        replace: &'static str,
    },
}

/// How a dialect casts one call-site argument to text.
///
/// The hash is a hash **of a string** and a call-site argument is a raw column
/// of its own declared type, so the cast is not optional.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TextCast {
    /// `CAST(x AS <type>)` — the cast propagates NULL, so Razeri's NULL
    /// sentinel is reached with the statement intact.
    Direct(&'static str),
    /// `assumeNotNull(CAST(x AS Nullable(<type>)))` — `ClickHouse`, whose
    /// `CAST` to a non-`Nullable` type **raises** instead of propagating
    /// (*"Cannot convert NULL to a non-nullable type"*).
    ///
    /// `ClickHouse` evaluates both arms of a `CASE`, so the sentinel cannot
    /// save the statement: the emitted key expression failed outright on any
    /// NULL natural-key part rather than returning the sentinel. That is not a
    /// wrong key — it is a dimension load that does not run. The wrapper makes
    /// the unreachable arm total; which value it would produce is irrelevant,
    /// because the sentinel has already answered.
    ClickHouseNullTolerant(&'static str),
}

/// How a dialect spells `TRIM`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Trim {
    /// `TRIM(x)`, in the platform's own casing.
    Function(&'static str),
    /// `LTRIM(RTRIM(x))` — T-SQL, whose `TRIM` requires SQL Server 2017. The
    /// pair removes the same leading and trailing spaces.
    LtrimRtrim,
    /// `TRIM(x, ' ')` — the engines whose **bare** `TRIM` removes every
    /// whitespace character rather than the ASCII space alone.
    ///
    /// The canonical trim is the ASCII space (`U+0020`) and nothing else, which
    /// is why a tab-padded and a newline-padded probe are in the corpus and are
    /// *not* expected to normalize away. `BigQuery` is the measured member:
    /// `LENGTH(TRIM('\tBoston\t'))` is 6 there — the tab gone and the key moved
    /// — while `LENGTH(TRIM('\tBoston\t', ' '))` is 8, and a non-breaking space
    /// survives the second form and not the first.
    ///
    /// The explicit set is not a repair of the engine; it is the canonical
    /// clause written in an engine whose default set is wider. `TRIM(x, ' ')`
    /// and `TRIM(x)` are the same function on every platform whose bare form
    /// already strips the space alone, so the variant states a difference
    /// rather than introducing one.
    ///
    /// **If you have not run a tab-padded probe on your engine, you do not yet
    /// know which variant is yours** — this one was found by executing the
    /// corpus on the service, and by nothing else. The community emulator this
    /// dialect was built against strips the space alone, which is the opposite
    /// answer.
    FunctionWithSpaceSet(&'static str),
}

/// How a dialect joins the normalized parts of a composite key.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Concat {
    /// `CONCAT(a, '|', b)`, in the platform's own casing.
    Function(&'static str),
    /// `a + '|' + b` — T-SQL's string operator. Equal to `CONCAT` for non-NULL
    /// operands, which Razeri's NULL sentinel is what guarantees: `+`
    /// propagates NULL where `CONCAT` swallows it, and a swallowed NULL
    /// silently collapses `('boston', NULL)` and `('boston', '')` into one
    /// member.
    Plus,
}

/// One platform's vocabulary for the surrogate-key derivation — the only thing
/// that varies between engines.
#[derive(Debug, Clone, Copy)]
pub struct SidSpelling {
    /// The name this dialect answers under. [`UNKNOWN_PLATFORM`] means the
    /// dialect has not stated a spelling and is taking ANSI's guess.
    pub platform: &'static str,
    /// The `LOWER` function, or the composition that stands in for it.
    pub lower: Lower,
    /// The `TRIM` function, or the pair that stands in for it.
    pub trim: Trim,
    /// The join used for composite keys.
    pub concat: Concat,
    /// The platform's hash of an already-normalized text expression, as the
    /// text before and after it. `("CAST(xxHash64(", ") AS Int64)")` reads
    /// `CAST(xxHash64(x) AS Int64)`.
    pub hash: (&'static str, &'static str),
    /// The CAST that turns one argument into text. The hash is a hash OF A
    /// STRING, and at the inline call sites the argument is a raw column of its
    /// own declared type — `TRIM(DATE)` is a binder error, not a value.
    pub cast_type: TextCast,
    /// Whether the load path reaches the hash through Razeri's emitted helper
    /// function instead of inlining it. Inlining is forced where a UDF cannot
    /// call another UDF (`DuckDB` macros, `ClickHouse` lambdas) and chosen
    /// where the platform's own function is already the derivation.
    pub through_helper: bool,
}

/// **ANSI's vocabulary** — the spelling a dialect inherits until it states its
/// own, and the agnostic renderer's answer on purpose.
///
/// A dialect building its own arm should start from this and change only the
/// fields its engine actually spells differently:
///
/// ```
/// use razeri_plugin_contract::{ANSI_SID_SPELLING, SidSpelling, TextCast};
///
/// const MY_ENGINE: SidSpelling = SidSpelling {
///     platform: "my-engine",
///     hash: ("my_xxhash64(", ")"),
///     cast_type: TextCast::Direct("STRING"),
///     through_helper: false,
///     ..ANSI_SID_SPELLING
/// };
/// ```
pub const ANSI_SID_SPELLING: SidSpelling = SidSpelling {
    platform: "ansi",
    lower: Lower::Function("LOWER"),
    trim: Trim::Function("TRIM"),
    concat: Concat::Function("CONCAT"),
    hash: ("xxhash64(", ")"),
    cast_type: TextCast::Direct("TEXT"),
    through_helper: true,
};

/// The spelling a dialect that has decided nothing renders — ANSI's vocabulary
/// under the name that says it is a guess.
pub const UNSPELLED_SID: SidSpelling =
    SidSpelling { platform: UNKNOWN_PLATFORM, ..ANSI_SID_SPELLING };

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn the_unspelled_default_differs_from_ansi_only_in_its_name() {
        assert_eq!(UNSPELLED_SID.platform, UNKNOWN_PLATFORM);
        assert_eq!(UNSPELLED_SID.hash, ANSI_SID_SPELLING.hash);
        assert_eq!(UNSPELLED_SID.lower, ANSI_SID_SPELLING.lower);
        assert_eq!(UNSPELLED_SID.trim, ANSI_SID_SPELLING.trim);
        assert_eq!(UNSPELLED_SID.concat, ANSI_SID_SPELLING.concat);
        assert_eq!(UNSPELLED_SID.cast_type, ANSI_SID_SPELLING.cast_type);
        assert_eq!(UNSPELLED_SID.through_helper, ANSI_SID_SPELLING.through_helper);
    }
}