razeri_plugin_api/

conformance.rs

// Copyright (C) 2026 Gabriel Shea
// Licensed under either of the Apache License, Version 2.0 or the MIT
// license, at your option.

//! **Every obligation a dialect owes, reported at once.**
//!
//! Two people built dialects against Razeri's authoring guide without help.
//! Between them they met twenty-seven obligations one `cargo test` at a time —
//! a roster fails, you add a row, the next roster fails. Not one of those
//! failures was discoverable before it fired. This module is the report that
//! answers all of them in one pass.
//!
//! # Running it
//!
//! From your own crate's tests, where your dialect is linked and Razeri's
//! registry can see it:
//!
//! ```no_run
//! # use razeri_plugin_api::conformance;
//! # fn example(my_dialect: &dyn razeri_plugin_api::PlatformDialect) {
//! let report = conformance::check(my_dialect);
//! assert!(report.is_clean(), "{report}");
//! # }
//! ```
//!
//! Inside Razeri's own repository, `razeri plugin conform <name>` prints the
//! same report for any registered platform, followed by the repository-side
//! obligations a command cannot run for you.
//!
//! # What it can and cannot see
//!
//! Everything here is read off the dialect object, so it works wherever your
//! plugin compiles. What it cannot do is run Razeri's frozen matrices or
//! regenerate its language bindings — those are commands, and
//! [`repository_obligations`] lists them in the order they are owed.
//!
//! # Your dialect's name
//!
//! Your platform's names are yours. `DialectInfo::name` is the one Razeri
//! reports, `aliases` is every other spelling a design may use for it, and the
//! resolver reads both off the dialects that are loaded — so the report asks
//! only that your own spellings reach you, and there is no table inside Razeri
//! for your platform to be missing from. The one thing it will tell you is that
//! a spelling you declared is one another loaded platform also answers to,
//! because then the spelling names neither of you.

use crate::PlatformDialect;
use razeri_plugin_contract::{
    ConstraintEnforcement, DataType, DdlRenderer, DialectCapabilities, DialectFamily, MergeShape,
    ProcedureForm, SqlRenderer, UNKNOWN_PLATFORM,
};
use std::fmt;

/// How much a finding matters.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum Severity {
    /// **This dialect will produce SQL its engine rejects.** Fix it before
    /// anything else.
    Blocking,
    /// **A question this dialect has not answered.** Razeri has a default and
    /// will use it; the default was written for a different engine.
    Unanswered,
    /// Worth a look. Nothing is broken.
    Note,
}

impl fmt::Display for Severity {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(match self {
            Self::Blocking => "must fix",
            Self::Unanswered => "unanswered",
            Self::Note => "worth a look",
        })
    }
}

/// One thing to fix, in the order a reader wants it: what is wrong, then what
/// to do about it.
#[derive(Debug, Clone)]
pub struct Finding {
    /// How much it matters.
    pub severity: Severity,
    /// One line naming what is wrong.
    pub what: String,
    /// One line naming what to do.
    pub fix: String,
}

/// A command a plugin author runs inside Razeri's repository, and why.
#[derive(Debug, Clone, Copy)]
pub struct Obligation {
    /// What this step is for.
    pub what: &'static str,
    /// The command, exactly as typed.
    pub command: &'static str,
}

/// The whole report for one dialect.
#[derive(Debug, Clone)]
pub struct Report {
    /// The dialect's registry name.
    pub dialect: String,
    /// Everything found, worst first.
    pub findings: Vec<Finding>,
}

impl Report {
    /// Whether nothing blocking or unanswered was found.
    ///
    /// Notes do not fail a report: they are observations, not obligations.
    #[must_use]
    pub fn is_clean(&self) -> bool {
        !self.findings.iter().any(|f| f.severity != Severity::Note)
    }

    /// How many findings of one severity.
    #[must_use]
    pub fn count(&self, severity: Severity) -> usize {
        self.findings.iter().filter(|f| f.severity == severity).count()
    }
}

impl fmt::Display for Report {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let name = &self.dialect;
        if self.findings.is_empty() {
            return writeln!(
                f,
                "{name}: nothing to fix. Every question Razeri asks a dialect, this one answers."
            );
        }
        let blocking = self.count(Severity::Blocking);
        let unanswered = self.count(Severity::Unanswered);
        let notes = self.count(Severity::Note);
        writeln!(f, "{name}: {blocking} to fix, {unanswered} unanswered, {notes} worth a look.")?;
        for finding in &self.findings {
            writeln!(f)?;
            writeln!(f, "  [{}] {}", finding.severity, finding.what)?;
            writeln!(f, "      → {}", finding.fix)?;
        }
        Ok(())
    }
}

/// **The report.** Everything about this dialect that Razeri can check by
/// asking it.
///
/// Registration is checked against the dialects linked into this program. A
/// dialect the host loaded at run time is not among them, so report it with
/// [`check_with_registry`] and the registry it was loaded into.
#[must_use]
pub fn check(dialect: &dyn PlatformDialect) -> Report {
    check_with_registry(dialect, &crate::dialect::PlatformRegistry::with_auto_discovered())
}

/// The same report, against a registry the host built — the path for a dialect
/// loaded at run time rather than linked in.
#[must_use]
pub fn check_with_registry(
    dialect: &dyn PlatformDialect,
    registry: &crate::dialect::PlatformRegistry,
) -> Report {
    let info = dialect.info();
    let mut findings = Vec::new();

    check_registration(&info, registry, &mut findings);
    check_family(info.dialect_family, &mut findings);
    check_required_rendering(dialect, &mut findings);
    check_decisions(dialect, &mut findings);
    check_formula_renderer(dialect, &mut findings);
    check_paired_facts(dialect, &mut findings);

    findings.sort_by_key(|f| f.severity);
    Report { dialect: info.name.to_owned(), findings }
}

/// Every spelling this dialect answers to has to reach this dialect: its own
/// name, and each alias it declares.
///
/// That is the whole obligation, and it is one the author can meet from their
/// own crate — the spellings are the dialect's own, so there is no list inside
/// Razeri to be missing from and nothing here can ask for a change only Razeri
/// could make. What is worth saying is a spelling that reaches somewhere else:
/// one another loaded platform also claims (so it names neither, and Razeri
/// refuses it), or one that reaches a different platform because the registry
/// holds this dialect under another key.
fn check_registration(
    info: &crate::dialect::DialectInfo,
    registry: &crate::dialect::PlatformRegistry,
    findings: &mut Vec<Finding>,
) {
    let name = info.name;
    if matches!(
        crate::resolve::resolve_dialect_by_name_with_registry(name, registry),
        Err(crate::ResolveError::UnknownDialect { .. })
    ) {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: format!(
                "the name `{name}` does not resolve — nothing in this program registered it"
            ),
            fix: "add `inventory::submit! { DialectRegistration::new(\"<name>\", || \
                  Arc::new(MyDialect)) }` to your crate, and a `pub fn force_link() {}` beside \
                  it that the program using your dialect calls once. A crate nothing links is a \
                  crate the registry cannot see."
                .to_owned(),
        });
        return;
    }
    for spelling in info.spellings() {
        match crate::resolve::resolve_dialect_by_name_with_registry(spelling, registry) {
            Ok(found) if found.info().name == name => {}
            Ok(found) => findings.push(Finding {
                severity: Severity::Blocking,
                what: format!("`{spelling}` reaches `{}` rather than `{name}`", found.info().name),
                fix: format!(
                    "the registry holds `{name}` under another key. Register it under its own \
                     name, or drop `{spelling}` from its aliases."
                ),
            }),
            Err(crate::ResolveError::AmbiguousName { claimed_by, .. }) => findings.push(Finding {
                severity: Severity::Blocking,
                what: format!(
                    "`{spelling}` is claimed by more than one loaded platform ({}), so it names \
                     none of them — Razeri refuses that spelling rather than guessing which one \
                     a design meant",
                    claimed_by.join(" and ")
                ),
                fix: format!(
                    "give this dialect a name no other platform answers to. A platform name is \
                     read off the loaded dialects' own declared spellings, so a spelling another \
                     platform already claims is never `{name}`'s."
                ),
            }),
            Err(_) => findings.push(Finding {
                severity: Severity::Blocking,
                what: format!(
                    "`{spelling}` is declared as a spelling of `{name}` but reaches no platform"
                ),
                fix: format!(
                    "the `{name}` in the registry is a different build of this dialect and does \
                     not declare `{spelling}`. Register the one you are grading."
                ),
            }),
        }
    }
}

/// A family is a claim about spelling, so an unmeasured engine claiming a
/// measured family's name licenses SQL it may reject.
fn check_family(family: DialectFamily, findings: &mut Vec<Finding>) {
    if matches!(family, DialectFamily::Custom(name) if name.trim().is_empty()) {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: "this dialect's family is a custom one with no name".to_owned(),
            fix: "give `DialectFamily::Custom` your engine's own name — it is what a report \
                  prints and what a reader looks up."
                .to_owned(),
        });
    }
}

/// The four required methods must answer for every type a design can declare.
fn check_required_rendering(dialect: &dyn PlatformDialect, findings: &mut Vec<Finding>) {
    let declarable = declarable_types();
    let empty_column: Vec<String> = declarable
        .iter()
        .filter(|dt| SqlRenderer::render_data_type(dialect, dt).trim().is_empty())
        .map(|dt| format!("{dt:?}"))
        .collect();
    if !empty_column.is_empty() {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: format!(
                "`render_data_type` answers nothing for {} of the types a design can declare",
                empty_column.len()
            ),
            fix: "every declarable type needs a column spelling on this engine, even if the \
                  spelling is a wider type that stores it. A blank answer becomes a column \
                  declaration with no type in it."
                .to_owned(),
        });
    }
    let empty_cast: Vec<String> = declarable
        .iter()
        .filter(|dt| SqlRenderer::render_cast_type(dialect, dt).trim().is_empty())
        .map(|dt| format!("{dt:?}"))
        .collect();
    if !empty_cast.is_empty() {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: format!(
                "`render_cast_type` answers nothing for {} declarable types",
                empty_cast.len()
            ),
            fix: "the generated load opens by casting every source column to its declared type, \
                  so a blank answer fails the load on its first statement."
                .to_owned(),
        });
    }
    let quoted = SqlRenderer::quote_identifier(dialect, "order");
    if quoted == "order" {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: "`quote_identifier` returns the identifier unchanged, so a reserved word \
                   reaches this engine bare"
                .to_owned(),
            fix: "wrap the identifier in whatever this engine quotes with — double quotes, \
                  backticks, or brackets."
                .to_owned(),
        });
    }
    if SqlRenderer::render_current_timestamp(dialect).trim().is_empty() {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: "`render_current_timestamp` answers nothing, and every generated load stamps \
                   a row with it"
                .to_owned(),
            fix: "return this engine's own expression for the current moment.".to_owned(),
        });
    }
}

/// The decisions a dialect states rather than inherits.
fn check_decisions(dialect: &dyn PlatformDialect, findings: &mut Vec<Finding>) {
    let spelling = SqlRenderer::sid_spelling(dialect);
    if spelling.platform == UNKNOWN_PLATFORM {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: "this dialect states no surrogate-key spelling, so every key it renders calls \
                   an `xxhash64` its engine very likely does not have"
                .to_owned(),
            fix: "override `SqlRenderer::sid_spelling`. Say what this engine calls LOWER and \
                  TRIM, how it joins strings, how it casts to text, and how it spells a 64-bit \
                  hash. If it has no portable hash, name an artifact your prerequisites install \
                  — never the nearest-looking built-in, which keys a warehouse to a number \
                  nothing else can reproduce."
                .to_owned(),
        });
    }

    match SqlRenderer::procedure_form(dialect) {
        // Razeri's own agnostic renderer answers `Agnostic` on purpose: the
        // annotated form IS its output. Every other dialect that answers it has
        // simply not said.
        ProcedureForm::Agnostic if SqlRenderer::is_agnostic_dialect(dialect) => {}
        ProcedureForm::Agnostic => findings.push(Finding {
            severity: Severity::Unanswered,
            what: "this dialect states no stored-procedure grammar, so Razeri emits its own \
                   annotated form — which no engine parses"
                .to_owned(),
            fix: "override `SqlRenderer::procedure_form` with the grammar this engine speaks, \
                  or with `ProcedureForm::Unsupported(\"…\")` and a sentence saying what it \
                  offers instead."
                .to_owned(),
        }),
        ProcedureForm::Unsupported(orientation) => {
            check_refusal_copy("the stored-procedure refusal", orientation, findings);
        }
        _ => {}
    }

    if let Some(orientation) = SqlRenderer::table_function_form(dialect).refusal() {
        check_refusal_copy("the table-function refusal", orientation, findings);
    }

    // The note is what a reader of the DDL learns from, and on an engine with
    // no keyword of its own it is the ONLY place they can learn it.
    if let ConstraintEnforcement::DeclaredOnly(declared) =
        DdlRenderer::constraint_enforcement(dialect)
        && declared.note.split_whitespace().count() < 5
    {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: "this dialect says its engine accepts constraints it does not enforce, and \
                   the note explaining that says almost nothing"
                .to_owned(),
            fix: "a reader of your rendered DDL sees a PRIMARY KEY that looks like a \
                  guarantee. Say what this engine really does with the declaration, and where \
                  the guarantee has to come from instead."
                .to_owned(),
        });
    }

    // **The two refusals are different findings, and that is the point of the
    // second variant.** `None` is silence, and silence is unanswered. A stated
    // `Unsupported` is a measured claim; what is left to grade there is whether
    // the sentence is worth reading, because it is the only thing an operator
    // gets where the load would have been.
    match DialectCapabilities::merge_shape(dialect) {
        MergeShape::None => findings.push(Finding {
            severity: Severity::Unanswered,
            what: "this dialect has not stated its upsert shape, so Razeri writes no generated \
                   load for it"
                .to_owned(),
            fix: "if this engine has a MERGE or an upsert statement, say which in \
                  `DialectCapabilities::merge_shape`. If it genuinely has neither, answer \
                  `MergeShape::Unsupported` with your engine's own sentence — a refusal an \
                  operator can act on, rather than a silence."
                .to_owned(),
        }),
        MergeShape::Unsupported(orientation) => {
            check_refusal_copy("the upsert refusal", orientation, findings);
        }
        _ => {}
    }
}

/// The one override nothing tells an author about, and every formula in every
/// design goes through it.
fn check_formula_renderer(dialect: &dyn PlatformDialect, findings: &mut Vec<Finding>) {
    let formula = SqlRenderer::to_formula_renderer(dialect);
    let dialect_name = SqlRenderer::dialect_name(dialect);
    if formula.dialect_name() != dialect_name && dialect_name != "ansi" {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: "`to_formula_renderer` was not overridden, so every formula in every design \
                   renders through Razeri's ANSI defaults instead of this dialect"
                .to_owned(),
            fix: "return `Box::new(Self)`. It is one line, nothing fails without it, and every \
                  formula this engine sees is silently somebody else's."
                .to_owned(),
        });
    }
}

/// A refusal that does not say what to do instead is a wall.
fn check_refusal_copy(subject: &str, copy: &str, findings: &mut Vec<Finding>) {
    if copy.trim().is_empty() {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: format!("{subject} has no words in it"),
            fix: "say what this engine offers instead. A reader who hits a refusal needs the \
                  next thing to try, and it has to be about their engine."
                .to_owned(),
        });
        return;
    }
    if copy.split_whitespace().count() < 5 {
        findings.push(Finding {
            severity: Severity::Note,
            what: format!("{subject} is very short"),
            fix: "a refusal earns its place by naming the alternative — what this engine has \
                  instead of the thing it cannot do."
                .to_owned(),
        });
    }
}

/// Fourteen facts are declared twice and must agree.
fn check_paired_facts(dialect: &dyn PlatformDialect, findings: &mut Vec<Finding>) {
    let caps: &dyn DialectCapabilities = dialect;
    let ren: &dyn SqlRenderer = dialect;
    let ddl: &dyn DdlRenderer = dialect;
    let mut disagreements: Vec<&'static str> = Vec::new();

    macro_rules! pair {
        ($m:ident, $renderer_value:expr) => {
            if caps.$m() != $renderer_value {
                disagreements.push(stringify!($m));
            }
        };
    }
    pair!(supports_on_conflict, ren.supports_on_conflict());
    pair!(supports_insert_overwrite, ren.supports_insert_overwrite());
    pair!(supports_update_from, ren.supports_update_from());
    pair!(supports_named_windows, ren.supports_named_windows());
    pair!(supports_compound_assignment, ren.supports_compound_assignment());
    pair!(supports_window_frame_exclude, ren.supports_window_frame_exclude());
    pair!(supports_merge_not_matched_by_source, ren.supports_merge_not_matched_by_source());
    pair!(merge_not_matched_keyword, ren.merge_not_matched_keyword());
    pair!(uses_alter_table_update, ren.uses_alter_table_update());
    pair!(supports_multi_table_insert, ren.supports_multi_table_insert());
    pair!(supports_cascade_drop, ddl.supports_cascade_drop());
    pair!(supports_sync_drop, ddl.supports_sync_drop());
    pair!(supports_force_drop, ddl.supports_force_drop());

    // **The fourteenth, whose two sides are different types.** The capability
    // is a boolean; the renderer answer is a form that either renders or
    // carries a refusal. Both are read — the build door reads the form, and
    // registry-walking rosters read the capability — so a dialect claiming a
    // table function on one side and refusing on the other has an engine that
    // both does and does not have one. `SQLite` was exactly that on the day
    // this check was written: `false` since the capability existed, and a
    // renderer still inheriting PostgreSQL's `RETURNS TABLE`.
    if caps.supports_table_functions() != ren.table_function_form().refusal().is_none() {
        disagreements.push("supports_table_functions");
    }

    if !disagreements.is_empty() {
        findings.push(Finding {
            severity: Severity::Blocking,
            what: format!(
                "this dialect declares {} fact(s) two ways and the two disagree: {}",
                disagreements.len(),
                disagreements.join(", ")
            ),
            fix: "each of these is declared once on the capability trait and once in the \
                  renderer hierarchy, and Razeri reads both. Decide which is true of your engine \
                  and move the other one to match."
                .to_owned(),
        });
    }
}

/// **What a command has to do for you**, in the order it is owed.
///
/// These are Razeri's repository obligations: frozen matrices, generated
/// bindings, and the allowlist a new crate joins. A dialect built outside this
/// repository owes none of them; a dialect built inside it owes all of them,
/// and each has an excellent failure message that nobody can read before it
/// fires.
#[must_use]
pub const fn repository_obligations() -> &'static [Obligation] {
    &[
        Obligation {
            what: "classify the new crate — every workspace member is named exactly once, and \
                   dialect crates are tier 1",
            command: "scripts/check-tier-boundary.sh",
        },
        Obligation {
            what: "freeze the DDL your platform renders for all eleven corpus designs",
            command: "UPDATE_GOLDEN=1 cargo test -p razeri-materialize --test golden_ddl",
        },
        Obligation {
            what: "freeze the derived-column projections your platform renders",
            command: "UPDATE_GOLDEN=1 cargo test -p razeri-materialize --test expression_matrix",
        },
        Obligation {
            what: "freeze the transaction envelope your platform renders",
            command: "UPDATE_GOLDEN=1 cargo test -p razeri-materialize \
                      --test load_transaction_matrix",
        },
        Obligation {
            what: "regenerate the typed platform constants for Python, TypeScript, Go, C# and \
                   Java",
            command: "cargo run -p razeri-dialects --bin gen-platform-constants",
        },
        Obligation {
            what: "give every registry-walking roster a row for your platform — they fail one \
                   at a time otherwise",
            command: "cargo test -p razeri-materialize -p razeri-sql",
        },
        Obligation {
            what: "prove the artifacts deploy and run: an execution leg per routine kind and \
                   per generated load is what finished means here",
            command: "cargo test -p integration-tests",
        },
    ]
}

/// Every type a design can declare, which is the set the required methods owe
/// an answer for.
fn declarable_types() -> Vec<DataType> {
    vec![
        DataType::tinyint(),
        DataType::smallint(),
        DataType::int(),
        DataType::bigint(),
        DataType::double(),
        DataType::boolean(),
        DataType::text(),
        DataType::varchar(200),
        DataType::uuid(),
        DataType::json(),
        DataType::date(),
        DataType::timestamp(),
        DataType::timestamp_tz(),
        DataType::decimal(18, 2),
    ]
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::dialect::DialectInfo;
    use razeri_plugin_contract::{
        DmlRenderer, ExpressionRenderer, FormulaRenderer, MergeRestrictions, ProcedureRenderer,
        ReplicationRenderer, ScalarFunctionForm, SidSpelling, StorageRenderer, TaskRenderer,
        TextCast,
    };
    use std::marker::PhantomData;

    // ── The broken fixture ────────────────────────────────────────────
    //
    // A plugin that compiles, registers nothing it should, and answers every
    // question with somebody else's default. This is what the kit exists to
    // catch, and it is deliberately the plugin an author gets by implementing
    // only the four required methods and stopping — which the guide, until
    // now, told them was enough.

    struct BrokenPlugin;

    impl SqlRenderer for BrokenPlugin {
        fn render_data_type(&self, _dt: &DataType) -> String {
            String::new()
        }
        fn quote_identifier(&self, name: &str) -> String {
            name.to_owned()
        }
        fn render_cast_type(&self, _dt: &DataType) -> String {
            String::new()
        }
        fn qualify_name(&self, _schema: Option<&str>, name: &str) -> String {
            name.to_owned()
        }
        fn render_current_timestamp(&self) -> String {
            String::new()
        }
        fn dialect_name(&self) -> &'static str {
            "brokendb"
        }
        // No `sid_spelling`, no `procedure_form`, no `to_formula_renderer` —
        // and one fact declared twice, two ways.
        fn supports_on_conflict(&self) -> bool {
            true
        }
    }
    impl ExpressionRenderer for BrokenPlugin {}
    impl DdlRenderer for BrokenPlugin {}
    impl DmlRenderer for BrokenPlugin {}
    impl ProcedureRenderer for BrokenPlugin {}
    impl FormulaRenderer for BrokenPlugin {}
    impl TaskRenderer for BrokenPlugin {}
    impl ReplicationRenderer for BrokenPlugin {}
    impl StorageRenderer for BrokenPlugin {}
    impl DialectCapabilities for BrokenPlugin {
        fn supports_on_conflict(&self) -> bool {
            false
        }
    }
    impl PlatformDialect for BrokenPlugin {
        fn info(&self) -> DialectInfo {
            DialectInfo {
                name: "brokendb",
                display_name: "Broken DB",
                aliases: &[],
                dialect_family: DialectFamily::Custom(""),
                family: "Broken",
                is_cloud_native: false,
                is_olap: false,
                is_postgres_compatible: false,
            }
        }
    }

    // ── The answered fixture, under two names ─────────────────────────
    //
    // The same plugin with every question answered, carrying the name it
    // registers under as a type parameter. Neither name is one Razeri knows a
    // spelling for; the difference is that one of them is in the registry and
    // the other is in nothing at all. Those are two different facts about a
    // dialect, and they read as two different reports.

    trait FixtureName: Send + Sync + 'static {
        /// The registry name this fixture answers to.
        const NAME: &'static str;
    }

    /// Answered, and nothing linked it — what an author sees running the report
    /// from a crate whose registration nobody calls.
    struct Unlinked;
    impl FixtureName for Unlinked {
        const NAME: &'static str = "healthydb";
    }

    /// Answered and registered, under a name Razeri ships no spelling for —
    /// the shape of every dialect written outside Razeri's own tree.
    struct Outside;
    impl FixtureName for Outside {
        const NAME: &'static str = "outsidedb";
    }

    struct Answered<N: FixtureName>(PhantomData<N>);

    impl<N: FixtureName> Answered<N> {
        const fn new() -> Self {
            Self(PhantomData)
        }
    }

    type HealthyPlugin = Answered<Unlinked>;
    type OutsidePlugin = Answered<Outside>;

    inventory::submit! {
        crate::builder::DialectRegistration::new(
            Outside::NAME,
            || std::sync::Arc::new(OutsidePlugin::new()),
        )
    }

    impl<N: FixtureName> SqlRenderer for Answered<N> {
        fn render_data_type(&self, dt: &DataType) -> String {
            razeri_plugin_contract::agnostic::render_data_type_ansi(dt)
        }
        fn quote_identifier(&self, name: &str) -> String {
            format!("\"{name}\"")
        }
        fn qualify_name(&self, schema: Option<&str>, name: &str) -> String {
            schema.map_or_else(
                || self.quote_identifier(name),
                |s| format!("{}.{}", self.quote_identifier(s), self.quote_identifier(name)),
            )
        }
        fn render_current_timestamp(&self) -> String {
            "NOW()".to_owned()
        }
        fn dialect_name(&self) -> &'static str {
            N::NAME
        }
        fn sid_spelling(&self) -> SidSpelling {
            SidSpelling {
                platform: N::NAME,
                hash: ("answered_xxhash64(", ")"),
                cast_type: TextCast::Direct("STRING"),
                through_helper: false,
                ..razeri_plugin_contract::ANSI_SID_SPELLING
            }
        }
        fn procedure_form(&self) -> ProcedureForm {
            ProcedureForm::Unsupported(
                "This engine has no stored procedures; write the load as a scheduled query \
                 instead.",
            )
        }
        fn scalar_function_form(&self) -> ScalarFunctionForm {
            ScalarFunctionForm::PostgreSql
        }
        fn to_formula_renderer(&self) -> Box<dyn FormulaRenderer> {
            Box::new(Self::new())
        }
    }
    impl<N: FixtureName> ExpressionRenderer for Answered<N> {}
    impl<N: FixtureName> DdlRenderer for Answered<N> {}
    impl<N: FixtureName> DmlRenderer for Answered<N> {}
    impl<N: FixtureName> ProcedureRenderer for Answered<N> {}
    impl<N: FixtureName> FormulaRenderer for Answered<N> {}
    impl<N: FixtureName> TaskRenderer for Answered<N> {}
    impl<N: FixtureName> ReplicationRenderer for Answered<N> {}
    impl<N: FixtureName> StorageRenderer for Answered<N> {}
    impl<N: FixtureName> DialectCapabilities for Answered<N> {
        fn merge_shape(&self) -> MergeShape {
            MergeShape::Merge(MergeRestrictions::none())
        }
    }
    impl<N: FixtureName> PlatformDialect for Answered<N> {
        fn info(&self) -> DialectInfo {
            DialectInfo {
                name: N::NAME,
                display_name: "An Answered Engine",
                // It answers to its own name and nothing else, which is the
                // shape of a plugin that declares no extra spellings.
                aliases: &[],
                dialect_family: DialectFamily::Custom(N::NAME),
                family: "Answered",
                is_cloud_native: false,
                is_olap: false,
                is_postgres_compatible: false,
            }
        }
    }

    // ── The twin: a dialect that claims a name another platform answers to ──
    //
    // Answered in every other respect, so the only thing its report can be
    // about is the spelling it took.

    struct Twin;

    impl SqlRenderer for Twin {
        fn render_data_type(&self, dt: &DataType) -> String {
            razeri_plugin_contract::agnostic::render_data_type_ansi(dt)
        }
        fn quote_identifier(&self, name: &str) -> String {
            format!("\"{name}\"")
        }
        fn qualify_name(&self, _schema: Option<&str>, name: &str) -> String {
            self.quote_identifier(name)
        }
        fn render_current_timestamp(&self) -> String {
            "NOW()".to_owned()
        }
    }
    impl ExpressionRenderer for Twin {}
    impl DdlRenderer for Twin {}
    impl DmlRenderer for Twin {}
    impl ProcedureRenderer for Twin {}
    impl FormulaRenderer for Twin {}
    impl TaskRenderer for Twin {}
    impl ReplicationRenderer for Twin {}
    impl StorageRenderer for Twin {}
    impl DialectCapabilities for Twin {}
    impl PlatformDialect for Twin {
        fn info(&self) -> DialectInfo {
            DialectInfo {
                name: "twindb",
                display_name: "Twin DB",
                // The name the answered fixture already answers to.
                aliases: &["healthydb"],
                dialect_family: DialectFamily::Custom("twindb"),
                family: "Twin",
                is_cloud_native: false,
                is_olap: false,
                is_postgres_compatible: false,
            }
        }
    }

    /// Every finding whose `what` line mentions one of these subjects.
    fn mentions(report: &Report, needle: &str) -> bool {
        report.findings.iter().any(|f| f.what.contains(needle) || f.fix.contains(needle))
    }

    /// **The kit's own red.** A plugin that implements the four required
    /// methods and stops is exactly what the guide used to produce, and every
    /// one of these findings is a defect a shipped dialect actually had.
    #[test]
    fn the_kit_catches_a_deliberately_broken_plugin() {
        let report = check(&BrokenPlugin);
        assert!(!report.is_clean(), "the broken plugin reported clean:\n{report}");

        assert!(mentions(&report, "does not resolve"), "unregistered:\n{report}");
        assert!(mentions(&report, "custom one with no name"), "unnamed family:\n{report}");
        assert!(mentions(&report, "render_data_type"), "empty column types:\n{report}");
        assert!(mentions(&report, "render_cast_type"), "empty cast types:\n{report}");
        assert!(mentions(&report, "identifier unchanged"), "no quoting:\n{report}");
        assert!(mentions(&report, "render_current_timestamp"), "no now():\n{report}");
        assert!(mentions(&report, "surrogate-key spelling"), "unspelled key:\n{report}");
        assert!(mentions(&report, "stored-procedure grammar"), "no procedure form:\n{report}");
        assert!(mentions(&report, "upsert shape"), "no merge shape:\n{report}");
        assert!(mentions(&report, "to_formula_renderer"), "formula renderer:\n{report}");
        assert!(mentions(&report, "supports_on_conflict"), "paired fact:\n{report}");

        assert!(
            report.count(Severity::Blocking) >= 8,
            "the broken plugin owes more than {} blocking fixes:\n{report}",
            report.count(Severity::Blocking)
        );
    }

    /// **The kit does not cry wolf.** The same plugin with its questions
    /// answered reports only what is actually true of it: it is not
    /// registered in this test binary, and nothing else.
    #[test]
    fn the_kit_reports_only_registration_on_a_plugin_that_answered_everything() {
        let report = check(&HealthyPlugin::new());
        let unregistered: Vec<&Finding> =
            report.findings.iter().filter(|f| f.what.contains("does not resolve")).collect();
        assert_eq!(unregistered.len(), 1, "the registration finding is the honest one here");
        assert_eq!(
            report.findings.len(),
            1,
            "a plugin that answered every question owes nothing else:\n{report}"
        );
    }

    /// **A dialect written outside Razeri reaches a clean report.** It is
    /// reached the way every out-of-tree dialect is reached — it registered, and
    /// the resolver reads the loaded dialects' own declared spellings — so there
    /// is nothing for Razeri to be missing it from and nothing for the report to
    /// ask of its author.
    #[test]
    fn a_dialect_registered_under_its_own_name_reaches_a_clean_report() {
        assert!(
            crate::resolve_dialect_by_name(Outside::NAME).is_ok(),
            "the fixture registers through the registry, which is the whole path being graded"
        );
        // The precondition that used to read "no row in Razeri's table": no
        // other loaded platform declares this name, so the fixture is reached
        // only because it registered and said so itself.
        let registry = crate::dialect::PlatformRegistry::with_auto_discovered();
        assert!(
            registry
                .list()
                .iter()
                .filter(|info| info.name != Outside::NAME)
                .all(|info| !info.answers_to(Outside::NAME)),
            "the fixture's name must be one no other platform claims"
        );

        let report = check(&OutsidePlugin::new());
        assert!(report.findings.is_empty(), "nothing is owed here:\n{report}");
        assert!(report.is_clean(), "and the report says so:\n{report}");
        assert_eq!(report.count(Severity::Blocking), 0, "{report}");
        assert!(
            report.to_string().contains("nothing to fix"),
            "a clean dialect is told it is clean:\n{report}"
        );
    }

    /// **A platform cannot be reachable under an alias but not under its own
    /// name.** That used to be a judgement about a hand-written table, which
    /// could spell a platform `mynew_db` and never `mynewdb`. A dialect now
    /// declares its own spellings and its own name leads them, so the defect is
    /// unrepresentable rather than caught — and this is the assertion that keeps
    /// it that way.
    #[test]
    fn a_platform_is_never_reachable_by_an_alias_but_not_by_its_own_name() {
        let registry = crate::dialect::PlatformRegistry::with_auto_discovered();
        for info in registry.list() {
            assert_eq!(
                info.spellings().first().copied(),
                Some(info.name),
                "a platform's own name leads its spellings"
            );
            assert!(info.answers_to(info.name), "{} answers to its own name", info.name);
        }
    }

    /// **A name another platform already answers to is a collision, not a
    /// registration.** A dialect claiming a spelling Healthy DB answers to is
    /// named as the collision it is — with both platforms named, and a fix its
    /// author can actually perform — rather than being reported as an
    /// unregistered platform, which is a different problem with a different fix.
    #[test]
    fn a_name_razeri_reads_as_another_platform_is_blocking_and_says_which() {
        let mut registry = crate::dialect::PlatformRegistry::new();
        registry.register("healthydb".to_owned(), std::sync::Arc::new(HealthyPlugin::new()));
        registry.register("twindb".to_owned(), std::sync::Arc::new(Twin));

        let report = check_with_registry(&Twin, &registry);
        let collision = report
            .findings
            .iter()
            .find(|f| f.what.contains("claimed by more than one loaded platform"))
            .unwrap_or_else(|| panic!("the collision is reported:\n{report}"));
        assert_eq!(collision.severity, Severity::Blocking, "{collision:?}");
        assert!(collision.what.contains("healthydb"), "the other platform is named: {collision:?}");
        assert!(collision.what.contains("twindb"), "{collision:?}");
        assert!(collision.fix.contains("name no other platform answers to"), "{collision:?}");
        assert!(
            !mentions(&report, "does not resolve"),
            "a collision is not an unregistered platform:\n{report}"
        );
    }

    /// A platform reached under its own name owes nothing, whatever the case or
    /// the surrounding whitespace, and a name nothing has ever heard of is
    /// simply unknown rather than a finding against this dialect.
    #[test]
    fn registration_is_silent_on_a_platform_reached_under_its_own_name() {
        let mut registry = crate::dialect::PlatformRegistry::new();
        registry.register("healthydb".to_owned(), std::sync::Arc::new(HealthyPlugin::new()));

        let mut findings = Vec::new();
        check_registration(&HealthyPlugin::new().info(), &registry, &mut findings);
        assert!(findings.is_empty(), "{findings:?}");

        for spelling in ["healthydb", "HealthyDB", "  healthydb  "] {
            assert!(
                crate::resolve::resolve_dialect_by_name_with_registry(spelling, &registry).is_ok(),
                "'{spelling}' is the same platform"
            );
        }
        assert!(
            crate::resolve::resolve_dialect_by_name_with_registry("nosuchdb", &registry).is_err()
        );
    }

    /// **A dialect the host loaded at run time can be graded at all.** [`check`]
    /// asks the dialects linked into this program, which one loaded from a
    /// shared library is not among; [`check_with_registry`] asks the registry it
    /// was loaded into, and the registration judgement is answered from there.
    #[test]
    fn a_dialect_the_host_loaded_reports_clean_against_its_own_registry() {
        let mut registry = crate::dialect::PlatformRegistry::new();
        registry.register("healthydb".to_owned(), std::sync::Arc::new(HealthyPlugin::new()));

        let report = check_with_registry(&HealthyPlugin::new(), &registry);
        assert!(
            report.is_clean(),
            "a loaded dialect that answered everything owes nothing:\n{report}"
        );
    }

    /// **Every fix an outside author can read is a fix in their own crate.** A
    /// report that names a file inside Razeri is telling an author to edit a
    /// tree they do not have, and the fix cannot be performed at all.
    #[test]
    fn no_fix_line_sends_an_author_into_razeris_own_tree() {
        let mut collided = crate::dialect::PlatformRegistry::new();
        collided.register("healthydb".to_owned(), std::sync::Arc::new(HealthyPlugin::new()));
        collided.register("twindb".to_owned(), std::sync::Arc::new(Twin));

        let mut fixes: Vec<String> = Vec::new();
        for report in [
            check(&BrokenPlugin),
            check(&HealthyPlugin::new()),
            check(&OutsidePlugin::new()),
            // The collision and the unregistered-name judgements, which are the
            // two registration findings an author can actually reach.
            check_with_registry(&Twin, &collided),
            check_with_registry(&Twin, &crate::dialect::PlatformRegistry::new()),
        ] {
            fixes.extend(report.findings.iter().map(|f| f.fix.clone()));
        }
        assert!(fixes.len() >= 10, "the sweep reached the findings: {}", fixes.len());
        for fix in &fixes {
            for path in ["schemas/", "crates/", ".json", "scripts/", "razeri-design"] {
                assert!(
                    !fix.contains(path),
                    "a fix line names `{path}`, which is not in the author's crate:\n  {fix}"
                );
            }
        }
    }

    /// **A stated refusal is a claim, and a claim owes the reader words** — the
    /// same grading every other refusal gets, because these words are the only
    /// thing an operator finds where the load would have been.
    #[test]
    fn a_stated_upsert_refusal_is_graded_as_copy_and_a_silent_one_as_unanswered() {
        let mut mute = Vec::new();
        check_refusal_copy("the upsert refusal", "no merge", &mut mute);
        assert_eq!(mute.len(), 1, "a three-word refusal is a wall: {mute:?}");
        assert!(mute[0].what.contains("the upsert refusal"), "{mute:?}");

        let silence = check(&BrokenPlugin);
        assert!(
            silence
                .findings
                .iter()
                .any(|f| f.severity == Severity::Unanswered && f.what.contains("upsert shape")),
            "a dialect that never answered is unanswered, not wrong:\n{silence}"
        );
        assert!(
            silence.findings.iter().any(|f| f.fix.contains("MergeShape::Unsupported")),
            "the fix line names the way to state a measured refusal:\n{silence}"
        );
    }

    /// The report leads with what to fix and says it in words a reader can
    /// act on — no identifiers from Razeri's own record-keeping, and a
    /// one-line count before the detail.
    #[test]
    fn the_report_reads_as_a_summary_then_a_fix_list() {
        let text = check(&BrokenPlugin).to_string();
        let first = text.lines().next().expect("a summary line");
        assert!(first.starts_with("brokendb:"), "{first}");
        assert!(first.contains("to fix"), "{first}");
        assert!(text.contains("      → "), "every finding names the fix:\n{text}");
    }

    /// The repository obligations are commands, in the order they are owed,
    /// and every one of them says what it is for.
    #[test]
    fn every_repository_obligation_names_a_command_and_a_reason() {
        let obligations = repository_obligations();
        assert!(obligations.len() >= 5);
        for o in obligations {
            assert!(!o.command.trim().is_empty(), "{o:?}");
            assert!(o.what.split_whitespace().count() >= 5, "{o:?}");
        }
    }
}