@@ -167,15 +167,16 @@ SELECT
   o.order_id,
   o.customer_id,
   p.amount_cents AS total_cents,
-  @cents_to_dollars("p.amount_cents") AS total_dollars
+  @py.cents_to_dollars("p.amount_cents") AS total_dollars
 FROM __ref("stg_orders") o
 JOIN __ref("stg_payments") p USING (order_id)
 ```
 
-Macros are plain Python functions that return SQL, kept next to the models that use them:
+Python macros are plain functions that return SQL, kept next to the models that use them; SQL
+macros in `macros/sql/` cover logic-free fragments with typed, checked arguments:
 
 ```python
-# models/marts/_sqlbuild/_macros/currency.py
+# models/marts/_sqlbuild/_macros/python/currency.py
 def cents_to_dollars(column: str) -> str:
     """Convert a cents integer column to a dollars decimal with two decimal places."""
     return f"ROUND(({column}) / 100.0, 2)"
 
@@ -43,7 +43,7 @@
 COLUMN_RE = re.compile(
     r'^\s+(\w+) \(type (\w+), nullable (true|false), description "([^"]*)"(, audits \[not_null\])?\)'
 )
-MACRO_CALL_RE = re.compile(r'@(macro_\d{3}_\d{5})\("([^"]*)"\)')
+MACRO_CALL_RE = re.compile(r'@py\.(macro_\d{3}_\d{5})\("([^"]*)"\)')
 CAST_RE = re.compile(r"CAST\(([^ ]+) AS (\w+)\) AS (\w+)")
 
 
@@ -201,7 +201,7 @@ def write_dbt(sqb: Path, out: Path, n: int) -> Path:
     base_re = re.compile(
         r'def (base_offset_\d{3})\(expression: str\) -> str:\n    return f"\(\{expression\} \+ 1\)"'
     )
-    for macro in sorted(sqb.glob("models/*/intermediate/clean/_sqlbuild/macros/*/*.py")):
+    for macro in sorted(sqb.glob("models/*/intermediate/clean/_sqlbuild/macros/python/*/*.py")):
         text = macro.read_text()
         name, ret = macro_def_re.search(text).groups()
         offset = offset_re.search(text)[1]
 
@@ -13,6 +13,7 @@ default = []
 test-support = []
 
 [dependencies]
+memchr.workspace = true
 polyglot-sql.workspace = true
 polyglot-sql-function-catalogs.workspace = true
 rayon.workspace = true
 
@@ -551,6 +551,7 @@ pub(crate) fn decode_outcome(
     let binding_validated: bool = decoder.flag()?;
     decoder.finish()?;
     let outcome = ModelOutcome {
+        sql_macro_findings: Vec::new(),
         analysis: ModelAnalysis {
             analysis_succeeded,
             columns,
 
@@ -30,6 +30,7 @@ use crate::assembly::analysis_session::_helpers::mappings::{
 };
 use crate::assembly::analysis_session::_helpers::mappings::{producers, waves};
 use crate::assembly::analysis_session::constants::{UNKNOWN_NULLABILITY, UNKNOWN_TYPE};
+use crate::assembly::analysis_session::main::resolved_cleaned_sql::resolved_cleaned_sql;
 use crate::assembly::analysis_session::models::{
     AnalysisSession, ColumnFact, ContractProof, DeferredCleaning, FinishedSession, LineageFacts,
     LineageRow, ModelAnalysis, ModelOutcome, ModelRequest, Phase, PivotOutcome, PivotTables,
@@ -38,6 +39,9 @@ use crate::assembly::analysis_session::models::{
 use crate::assembly::analysis_session::types::{Pairs, Shapes};
 use crate::semantic_validation::models::DiagnosticRow;
 use crate::semantic_validation::models::ProjectCatalog;
+use crate::sql_macros::main::check_sql_macro_arguments::check_sql_macro_arguments;
+use crate::sql_macros::models::SqlMacroFinding;
+use crate::sql_macros::types::ArgumentCheckInput;
 
 /// What an internal native failure of the session names.
 const SESSION_CONTEXT: &str = "native model analysis";
@@ -279,13 +283,56 @@ impl AnalysisSession {
                 }
             };
             self.outcomes[*model] = Some(ModelOutcome {
+                sql_macro_findings: Vec::new(),
                 analysis,
                 cleaned_sql: result.cleaned_sql,
                 deferred_cleaning: None,
                 validated_schema: schema,
                 fused_binding_validated: true,
             });
         }
+        self.check_sql_macros(models)
+    }
+
+    /// Each model's SQL macro call arguments checked against its analysed types, cache hits too.
+    fn check_sql_macros(&mut self, models: &[usize]) -> Result<(), String> {
+        let checked: Vec<usize> = models
+            .iter()
+            .copied()
+            .filter(|model| {
+                let request: &ModelRequest = &self.request.models[*model];
+                !request.sql_macro_checks.is_empty() && request.placeholders.is_empty()
+            })
+            .collect();
+        self.ensure_cleaned(&checked)?;
+        let mut inputs: Vec<(usize, String, Shapes)> = Vec::with_capacity(checked.len());
+        for model in checked {
+            let Some(outcome) = self.outcomes[model].as_ref() else {
+                continue;
+            };
+            let Ok(cleaned) = resolved_cleaned_sql(outcome) else {
+                continue;
+            };
+            let schema: Shapes = self.binding_schema(&self.request.models[model]);
+            inputs.push((model, cleaned.into_owned(), schema));
+        }
+        let batch: Vec<ArgumentCheckInput<'_>> = inputs
+            .iter()
+            .map(|(model, cleaned, schema)| {
+                (
+                    cleaned.as_str(),
+                    schema.as_slice(),
+                    self.request.models[*model].sql_macro_checks.as_slice(),
+                )
+            })
+            .collect();
+        let findings: Vec<Vec<SqlMacroFinding>> =
+            check_sql_macro_arguments(&self.request.dialect, &batch);
+        for ((model, _, _), found) in inputs.iter().zip(findings) {
+            if let Some(outcome) = self.outcomes[*model].as_mut() {
+                outcome.sql_macro_findings = found;
+            }
+        }
         Ok(())
     }
 
 
@@ -12,6 +12,7 @@ use crate::assembly::analysis_session::_helpers::catalog_state::SessionCatalog;
 use crate::assembly::analysis_session::_helpers::mappings::ShapeTable;
 use crate::assembly::analysis_session::types::{NullabilityRuleFn, OutputSources, Pairs, Shapes};
 use crate::semantic_validation::models::DiagnosticRow;
+use crate::sql_macros::models::{SqlMacroCheck, SqlMacroFinding};
 
 /// One `ref`, `source`, `seed`, `table_fn` or `udf` call a model's SQL makes.
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -42,6 +43,8 @@ pub struct ModelRequest {
     /// The SQL Python's dynamic pivot proof parses: placeholders replaced by their defaults.
     pub pivot_sql: String,
     pub dynamic_families: Vec<DynamicFamily>,
+    /// What the model's analysed SQL must show for its SQL macro calls' arguments to fit.
+    pub sql_macro_checks: Vec<SqlMacroCheck>,
 }
 
 /// The reference-derived fields of a `ModelRequest`.
@@ -258,6 +261,8 @@ pub struct ModelOutcome {
     pub deferred_cleaning: Option<DeferredCleaning>,
     pub validated_schema: Shapes,
     pub fused_binding_validated: bool,
+    /// The SQL macro call arguments the analysed SQL shows do not fit; never cached.
+    pub sql_macro_findings: Vec<SqlMacroFinding>,
 }
 
 /// The finished run of the session: what Python records from it.
 
@@ -108,6 +108,7 @@ pub(crate) fn model(name: &str, sql: &str, sources: &[&str], refs: &[&str]) -> M
         snapshot_columns: None,
         pivot_sql: sql.to_owned(),
         dynamic_families: Vec::new(),
+        sql_macro_checks: Vec::new(),
     }
 }
 
 
@@ -67,6 +67,8 @@ pub fn locate_binding_diagnostics(
             line,
             column,
             location,
+            help: None,
+            related: None,
         });
     }
     Ok(located)
 
@@ -42,4 +42,15 @@ pub struct LocatedDiagnostic {
     pub line: Option<usize>,
     pub column: Option<usize>,
     pub location: Option<AuthoredSpan>,
+    pub help: Option<String>,
+    pub related: Option<RelatedSpot>,
+}
+
+/// A second authored location that adds context to a diagnostic.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct RelatedSpot {
+    pub label: String,
+    pub path: String,
+    pub line: usize,
+    pub column: usize,
 }
Original file line number	Diff line number	Diff line change
`@@ -108,6 +108,7 @@ pub(crate) fn model(name: &str, sql: &str, sources: &[&str], refs: &[&str]) -> M`
`108`	`108`	`snapshot_columns: None,`
`109`	`109`	`pivot_sql: sql.to_owned(),`
`110`	`110`	`dynamic_families: Vec::new(),`
	`111`	`+ sql_macro_checks: Vec::new(),`
`111`	`112`	`}`
`112`	`113`	`}`
`113`	`114`
Original file line number	Diff line number	Diff line change
`@@ -67,6 +67,8 @@ pub fn locate_binding_diagnostics(`
`67`	`67`	`line,`
`68`	`68`	`column,`
`69`	`69`	`location,`
	`70`	`+ help: None,`
	`71`	`+ related: None,`
`70`	`72`	`});`
`71`	`73`	`}`
`72`	`74`	`Ok(located)`