razeri-plugin-contract 0.5.0

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

#![warn(missing_docs)]

//! # razeri-plugin-contract
//!
//! **The contract a Razeri dialect plugin is written against.**
//!
//! This crate and `razeri-plugin-api` are the two open crates in Razeri's
//! workspace. Everything a plugin author needs in order to *describe* and
//! *render* a database platform lives here; nothing else does. It depends on
//! `serde` and on nothing else at all, which is what lets a plugin be built,
//! published and consumed outside this repository.
//!
//! ## What is in here
//!
//! **The rendering hierarchy** — ten traits, layered so that a new dialect
//! implements four required methods and inherits ANSI-standard behaviour for
//! the rest:
//!
//! 1. [`SqlRenderer`] — core SQL rendering (the four required methods)
//! 2. [`ExpressionRenderer`] — expressions, with ANSI defaults
//! 3. [`DdlRenderer`] — DDL, with ANSI defaults
//! 4. [`DmlRenderer`] — DML, with ANSI defaults
//! 5. [`ProcedureRenderer`] — stored procedures and functions
//! 6. [`FormulaRenderer`] — formulas, with ANSI defaults
//! 7. [`TaskRenderer`] — scheduled tasks
//! 8. [`ReplicationRenderer`] — data extraction, loading and key-function deployment
//! 9. [`StorageRenderer`] — partitioning, compression and index strategy
//! 10. [`DialectCapabilities`] — what the platform's SQL can and cannot do
//!
//! **The vocabulary those traits speak**: [`DataType`] and [`DataTypeRef`], the
//! [`storage_strategy::StoragePlan`] a [`StorageRenderer`] translates, the
//! [`StoragePlatform`] a storage plugin names, and [`DialectFamily`], the
//! platform's own identity.
//!
//! **The spelling a source gives a day** — [`date_format`]. One import
//! arrives with `1/1/2015` in one column and `2015-01-01T00:00:00Z` in the
//! next; the design states the spelling, this crate reads it once into a list
//! of directives, and each engine translates that list into its own pattern
//! language through [`ExpressionRenderer::render_parse_datetime`]. A directive
//! an engine cannot spell is refused by name.
//!
//! **The fan-out an engine states** — [`flatten`]. One row holding an array
//! becomes one row per element, and every engine spells that differently, so
//! the dialect answers with the whole shape rather than filling in a template.
//!
//! **The decisions a dialect states rather than a core crate deciding for it**,
//! starting with [`SidSpelling`] — how this engine spells a surrogate key —
//! and continuing with [`ProcedureForm`] and [`ScalarFunctionForm`], the
//! routine grammars it speaks, [`MergeShape`], how it upserts, and
//! [`EvolutionAnswers`], what it keeps when a table that already holds rows
//! changes shape.
//!
//! **The surrogate key's composition** — [`sid`] turns a [`SidSpelling`] into
//! the key expression an engine runs. It is here rather than in the product
//! because a dialect author who cannot render their own key expression cannot
//! run it either, and *"the same key on every engine"* is then a claim nobody
//! outside this repository can check.
//!
//! **The named routine grammars, spelled** — [`routine_render`]. A dialect
//! whose engine has stored procedures in a grammar of its own renders the whole
//! `CREATE` itself, and *"PL/pgSQL with one tweak"* used to mean writing the
//! whole thing from nothing. These three functions write out the grammar a
//! dialect is nearly the same as, so it can start there and say what differs.
//!
//! ## What is deliberately not in here
//!
//! Razeri's design model, and the renderers that turn it into Razeri's own
//! output. A plugin says what its engine spells; Razeri composes. That division
//! is why one contract crate can be open while the product is not.
//!
//! The routine grammars are the one thing on both sides of that line, and they
//! are here because they belong to the engines rather than to Razeri's design: a
//! plugin author who cannot read the grammar next to theirs has to guess at it.
//!
//! ## How this crate is versioned
//!
//! While the major version is zero:
//!
//! - **a change to a trait's method set bumps the minor version** — a method
//!   added, removed or renamed, whether or not it carries a default body;
//! - **documentation and fixes bump the patch version.**
//!
//! The rule is about who decides when a plugin's behaviour changes. Cargo
//! flows a patch release to every plugin pinned at the minor the next time it
//! builds, and flows a minor release to nobody. A defaulted method costs an
//! existing plugin no line of code, and it still changes what that plugin
//! *says*: an engine that has not implemented the new method now answers the
//! default, and its users meet whatever Razeri does with that answer — a
//! refusal they had never seen, arriving because somebody else released. So a
//! new method is opted into, and the plugin author chooses the day.
//!
//! This is stricter than semantic versioning requires of a zero-major crate,
//! deliberately: the looser reading saves a version number and spends a
//! plugin author's afternoon.
//!
//! ### What 0.5.0 adds to the method set
//!
//! - [`StorageRenderer::render_partition_retain_procedure`] takes the
//!   companion table a load sets rows aside in, so one call to a retention
//!   procedure reaches both tables.
//! - [`ExpressionRenderer::render_parse_datetime`] renders the parse of a
//!   value the source spells its own way into a date or a timestamp.

pub mod agnostic;
pub mod capabilities;
pub mod constraint_enforcement;
pub mod data_type;
pub mod date_format;
pub mod dialect_family;
pub mod evolution;
pub mod flatten;
pub mod formula_renderer;
pub mod merge_shape;
pub mod procedure_log_level;
pub mod renderer;
pub mod replication;
pub mod routine_form;
pub mod routine_render;
pub mod routine_spec;
pub mod sid;
pub mod sid_spelling;
pub mod storage_platform;
pub mod storage_renderer;
pub mod storage_strategy;
pub mod task_renderer;

pub use agnostic::*;
pub use capabilities::*;
pub use constraint_enforcement::*;
pub use data_type::{DataType, DataTypeRef};
pub use date_format::{DateFormat, DateFormatError, FormatDirective, FormatPart};
pub use dialect_family::DialectFamily;
pub use evolution::*;
pub use flatten::{Flatten, FlattenField, FlattenRequest};
pub use formula_renderer::*;
pub use merge_shape::*;
pub use procedure_log_level::ProcedureLogLevel;
pub use renderer::*;
pub use replication::*;
pub use routine_form::*;
pub use routine_render::{
    render_procedure_as, render_scalar_function_as, render_table_function_as,
};
pub use routine_spec::*;
pub use sid::sid_expression;
pub use sid_spelling::*;
pub use storage_platform::StoragePlatform;
pub use storage_renderer::*;
pub use task_renderer::*;