ddxdb 0.1.0__tar.gz

ddxdb-0.1.0/Cargo.toml

@@ -0,0 +1,58 @@
+# ddx — portable autograd for composable databases.
+#
+# One engine-neutral differentiation core (`ddx-core`, v1 / M0) plus thin
+# per-engine adapters. See docs/design.md §6 for the layout and the
+# dependency policy: `ddx-core` depends on `sqlparser` only; the heavy
+# per-engine dependencies (datafusion, duckdb) are quarantined in the
+# adapter crates.
+[workspace]
+resolver = "2"
+members = [
+    "crates/ddx-core",
+    "crates/ddx-ad",
+    "crates/ddx-datafusion",
+]
+
+[workspace.package]
+version = "0.0.0"
+edition = "2021"
+license = "Apache-2.0"
+repository = "https://github.com/xqlsystems/ddx"
+authors = ["Alexander Merose <al@merose.com>"]
+# MSRV. Enforced by the CI `msrv` matrix entry. The floor is set by a
+# transitive build-dependency (ar_archive_writer, which uses edition 2024);
+# ddx-core's own code needs far less, but the resolved tree does not build below
+# this. Bump only with a matching CI change.
+rust-version = "1.88"
+
+[workspace.dependencies]
+# The single load-bearing dependency of the core. Pinned exactly (see the
+# `sqlparser` version policy in docs/design.md §6): a bump is a breaking
+# release of ddx-core. 0.62 is the version every M0 spike was verified
+# against (spikes/sqlparser-spike, decision-log G1/G3).
+sqlparser = { version = "=0.62.0", features = ["visitor"] }
+
+# The DataFusion adapter's engine dependency (M2), quarantined to
+# `ddx-datafusion` — neither core crate may depend on it.
+#
+# The version is load-bearing for Path B, not incidental. The bridge unparses a
+# bound DataFusion `Expr` into a `sqlparser::ast::Expr` and hands it to
+# ddx-core, so the two crates MUST resolve the *identical* `sqlparser` — a
+# mismatch makes them two unrelated Rust types and the bridge stops compiling
+# datafusion 54.x requires `sqlparser ^0.62.0`,
+# which unifies with the exact `=0.62.0` pin above; 53.x wanted ^0.61 and would
+# NOT. `crates/ddx-datafusion/tests/sqlparser_pin.rs` asserts the resolved tree
+# still has exactly one `sqlparser`, so a future bump fails loudly at the pin
+# instead of confusingly at the bridge.
+datafusion = { version = "54" }
+
+# Internal crates, referenced by path within the workspace.
+#
+# `ddx-core` carries a `version` as well as a `path`: cargo uses the path for
+# workspace builds and the version for what it writes into a published
+# dependent's manifest, and it refuses to publish a crate whose path dependency
+# has no version. The floor is 0.2.1 rather than 0.2 because `grad(abs(u), x)`
+# returned a zero gradient for a NULL row in 0.2.0, and an adapter that resolved
+# to it would hand users that bug.
+ddx-core = { path = "crates/ddx-core", version = "0.2.1" }
+ddx-ad = { path = "crates/ddx-ad" }

ddxdb-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: ddxdb
+Version: 0.1.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Dist: datafusion>=45 ; extra == 'datafusion'
+Requires-Dist: duckdb>=1.0 ; extra == 'duckdb'
+Requires-Dist: pytest>=7 ; extra == 'test'
+Requires-Dist: datafusion>=45 ; extra == 'test'
+Requires-Dist: duckdb>=1.0 ; extra == 'test'
+Provides-Extra: datafusion
+Provides-Extra: duckdb
+Provides-Extra: test
+Summary: SQL-portable autograd: write calculus in SQL, get derivatives back as columns.
+Keywords: sql,autograd,derivatives,datafusion,duckdb
+Author-email: Alexander Merose <al@merose.com>
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/xqlsystems/ddx
+Project-URL: Repository, https://github.com/xqlsystems/ddx
+
+# ddxdb
+
+Write calculus directly in SQL and let the database evaluate the derivative, row
+by row, alongside everything else:
+
+```sql
+SELECT i, grad(x * y, x) AS dfdx, grad(x * y, y) AS dfdy FROM g
+```
+
+`grad` and `jvp` are **markers**, not row functions. They are rewritten away into
+ordinary derivative SQL *before* the engine sees them, so what runs is a plain
+expression — the relational equivalent of `jax.vmap(jax.grad(f))`, with the rows
+as the batch dimension.
+
+This is the Python distribution of [`ddx`](https://github.com/xqlsystems/ddx), a
+thin wrapper over the `ddx-core` engine.
+
+## Install
+
+```bash
+pip install ddxdb                  # everything below except Context
+pip install "ddxdb[datafusion]"    # + the DataFusion Context
+```
+
+## `rewrite_sql` is the whole library
+
+Text in, text out — so it works with **any** engine that accepts SQL. Pass the
+result wherever you would have passed the original:
+
+```python
+import ddxdb
+
+ddxdb.rewrite_sql("SELECT grad(sin(x), x) AS d FROM t")
+# 'SELECT (cos(x)) AS d FROM t'
+
+con.sql(ddxdb.rewrite_sql(q, "duckdb"))        # DuckDB
+session.sql(ddxdb.rewrite_sql(q, "spark"))     # Spark
+ctx.sql(ddxdb.rewrite_sql(q))                  # DataFusion
+```
+
+Accepted dialects: `generic`, `datafusion`, `postgres`, `ansi`, `snowflake`,
+`oracle`, `duckdb`, `mysql`, `sqlite`, `bigquery`, `redshift`, `hive`, `spark`,
+`databricks`, `mssql`, `teradata`, `clickhouse`.
+
+Pick the one that matches the engine you will run on, not just the one that
+parses your SQL. The dialect also decides which column an identifier *names*,
+and engines disagree three ways:
+
+| | unquoted `X` means | so `"X"` is |
+|---|---|---|
+| Postgres, DataFusion, generic, ansi | `"x"` | a different column |
+| Snowflake, Oracle | `"X"` | the same column |
+| DuckDB, Spark, MySQL, SQLite, BigQuery, Redshift, Hive, Databricks, SQL Server, Teradata | any casing | the same column |
+| ClickHouse | `X` exactly | the same column, and `"x"` is not |
+
+Getting this wrong does not raise. `grad("X" * "X", X)` is `2X` on Snowflake and
+`0` on Postgres — both correct, for different engines — so ddx keeps a table
+rather than a default, and refuses a dialect whose rule it has not established.
+
+Because the rewrite happens in *your* process, on *your* connection, it sees
+your temp tables, session settings, and open transaction. DuckDB's in-database
+`ddx('<sql>')` table function cannot: it executes on a separate inner
+connection.
+
+## `Context`, for DataFusion
+
+A real `SessionContext` subclass whose `.sql()` rewrites first — every inherited
+method, property and constructor argument works unchanged:
+
+```python
+ctx = ddxdb.Context()
+ctx.sql("SELECT grad(x * x, x) AS d FROM t").collect()      # → 2x
+```
+
+It lives in `ddxdb.datafusion` (a subclass needs its base class at import time,
+so it cannot sit beside `rewrite_sql` without dragging DataFusion in) and is
+re-exported as `ddxdb.Context`, imported on first use. `import ddxdb` still needs
+no engine.
+
+There is sugar for DataFusion and not for other engines because DataFusion is
+ddx's integration target. Everything else uses the one-liner above, which is why
+there are no per-engine helpers here to drift out of date.
+
+## What you can write
+
+`+ - * /`; the chain rule for the trig / inverse-trig / exp / log / hyperbolic
+set plus `abs`; `power` with a constant base or exponent. Higher order falls out
+of nesting — `grad(grad(f, x), x)` just works. Differentiating through an
+aggregate is linearity, so the marker goes *inside* it, which is what makes a
+gradient-descent step expressible in SQL:
+
+```sql
+SELECT theta - 0.01 * AVG(grad(loss, theta)) FROM batch
+```
+
+A marker rewrites in place, so it is legal anywhere a scalar expression is —
+including inside a recursive CTE, which is how a whole training loop fits in one
+query.
+
+## One other function
+
+```python
+ddxdb.differentiate_sql("x * y", "x")     # 'y' — the derivative as text
+```
+
+The escape hatch, for assembling SQL where a marker cannot reach — inside a
+recursive term you are building programmatically, or a query some other tool
+emits. Everything else should use `rewrite_sql`.
+
+## Errors are typed
+
+An unsupported construct is always an error, never a silently wrong number —
+this is a numerical-correctness library, and a plausible-looking wrong
+derivative is the worst thing it could produce. The kind of failure is a class,
+so you can catch the one you can act on:
+
+```python
+try:
+    ddxdb.rewrite_sql(query)
+except ddxdb.UnsupportedExpression:
+    ...   # no rule for something in there — fall back
+except ddxdb.AmbiguousColumn:
+    ...   # the query needs a qualifier — a fix the caller makes
+```
+
+All of them derive from `ddxdb.DdxError`. The full set is
+`UnsupportedExpression`, `InvalidMarker`, `AmbiguousColumn`,
+`ProjectionBoundary` and `SqlParseError`.
+
+## One thing to know
+
+**`grad` does not see through a CTE or a view.** Differentiation stops at column
+references, so a column computed upstream is a constant to it:
+
+```sql
+WITH v AS (SELECT x, sin(x) AS s FROM t)
+SELECT grad(s * x, x) FROM v       -- ds/dx is treated as 0
+```
+
+That is defensible relational semantics and a real trap, so ddx refuses the
+worst case rather than quietly dropping the term: referencing a computed CTE
+alias as a non-`wrt` term raises `ProjectionBoundary` and tells you to
+differentiate inside the CTE instead. Differentiating *with respect to* such an
+alias is fine — every occurrence is then the differentiation leaf, and
+`grad(s * s, s)` is exactly `2s`.
+
+## Development
+
+```bash
+pip install maturin pytest
+maturin develop --uv
+python -m pytest tests/
+```
+

ddxdb-0.1.0/README.md

@@ -0,0 +1,153 @@
+# ddxdb
+
+Write calculus directly in SQL and let the database evaluate the derivative, row
+by row, alongside everything else:
+
+```sql
+SELECT i, grad(x * y, x) AS dfdx, grad(x * y, y) AS dfdy FROM g
+```
+
+`grad` and `jvp` are **markers**, not row functions. They are rewritten away into
+ordinary derivative SQL *before* the engine sees them, so what runs is a plain
+expression — the relational equivalent of `jax.vmap(jax.grad(f))`, with the rows
+as the batch dimension.
+
+This is the Python distribution of [`ddx`](https://github.com/xqlsystems/ddx), a
+thin wrapper over the `ddx-core` engine.
+
+## Install
+
+```bash
+pip install ddxdb                  # everything below except Context
+pip install "ddxdb[datafusion]"    # + the DataFusion Context
+```
+
+## `rewrite_sql` is the whole library
+
+Text in, text out — so it works with **any** engine that accepts SQL. Pass the
+result wherever you would have passed the original:
+
+```python
+import ddxdb
+
+ddxdb.rewrite_sql("SELECT grad(sin(x), x) AS d FROM t")
+# 'SELECT (cos(x)) AS d FROM t'
+
+con.sql(ddxdb.rewrite_sql(q, "duckdb"))        # DuckDB
+session.sql(ddxdb.rewrite_sql(q, "spark"))     # Spark
+ctx.sql(ddxdb.rewrite_sql(q))                  # DataFusion
+```
+
+Accepted dialects: `generic`, `datafusion`, `postgres`, `ansi`, `snowflake`,
+`oracle`, `duckdb`, `mysql`, `sqlite`, `bigquery`, `redshift`, `hive`, `spark`,
+`databricks`, `mssql`, `teradata`, `clickhouse`.
+
+Pick the one that matches the engine you will run on, not just the one that
+parses your SQL. The dialect also decides which column an identifier *names*,
+and engines disagree three ways:
+
+| | unquoted `X` means | so `"X"` is |
+|---|---|---|
+| Postgres, DataFusion, generic, ansi | `"x"` | a different column |
+| Snowflake, Oracle | `"X"` | the same column |
+| DuckDB, Spark, MySQL, SQLite, BigQuery, Redshift, Hive, Databricks, SQL Server, Teradata | any casing | the same column |
+| ClickHouse | `X` exactly | the same column, and `"x"` is not |
+
+Getting this wrong does not raise. `grad("X" * "X", X)` is `2X` on Snowflake and
+`0` on Postgres — both correct, for different engines — so ddx keeps a table
+rather than a default, and refuses a dialect whose rule it has not established.
+
+Because the rewrite happens in *your* process, on *your* connection, it sees
+your temp tables, session settings, and open transaction. DuckDB's in-database
+`ddx('<sql>')` table function cannot: it executes on a separate inner
+connection.
+
+## `Context`, for DataFusion
+
+A real `SessionContext` subclass whose `.sql()` rewrites first — every inherited
+method, property and constructor argument works unchanged:
+
+```python
+ctx = ddxdb.Context()
+ctx.sql("SELECT grad(x * x, x) AS d FROM t").collect()      # → 2x
+```
+
+It lives in `ddxdb.datafusion` (a subclass needs its base class at import time,
+so it cannot sit beside `rewrite_sql` without dragging DataFusion in) and is
+re-exported as `ddxdb.Context`, imported on first use. `import ddxdb` still needs
+no engine.
+
+There is sugar for DataFusion and not for other engines because DataFusion is
+ddx's integration target. Everything else uses the one-liner above, which is why
+there are no per-engine helpers here to drift out of date.
+
+## What you can write
+
+`+ - * /`; the chain rule for the trig / inverse-trig / exp / log / hyperbolic
+set plus `abs`; `power` with a constant base or exponent. Higher order falls out
+of nesting — `grad(grad(f, x), x)` just works. Differentiating through an
+aggregate is linearity, so the marker goes *inside* it, which is what makes a
+gradient-descent step expressible in SQL:
+
+```sql
+SELECT theta - 0.01 * AVG(grad(loss, theta)) FROM batch
+```
+
+A marker rewrites in place, so it is legal anywhere a scalar expression is —
+including inside a recursive CTE, which is how a whole training loop fits in one
+query.
+
+## One other function
+
+```python
+ddxdb.differentiate_sql("x * y", "x")     # 'y' — the derivative as text
+```
+
+The escape hatch, for assembling SQL where a marker cannot reach — inside a
+recursive term you are building programmatically, or a query some other tool
+emits. Everything else should use `rewrite_sql`.
+
+## Errors are typed
+
+An unsupported construct is always an error, never a silently wrong number —
+this is a numerical-correctness library, and a plausible-looking wrong
+derivative is the worst thing it could produce. The kind of failure is a class,
+so you can catch the one you can act on:
+
+```python
+try:
+    ddxdb.rewrite_sql(query)
+except ddxdb.UnsupportedExpression:
+    ...   # no rule for something in there — fall back
+except ddxdb.AmbiguousColumn:
+    ...   # the query needs a qualifier — a fix the caller makes
+```
+
+All of them derive from `ddxdb.DdxError`. The full set is
+`UnsupportedExpression`, `InvalidMarker`, `AmbiguousColumn`,
+`ProjectionBoundary` and `SqlParseError`.
+
+## One thing to know
+
+**`grad` does not see through a CTE or a view.** Differentiation stops at column
+references, so a column computed upstream is a constant to it:
+
+```sql
+WITH v AS (SELECT x, sin(x) AS s FROM t)
+SELECT grad(s * x, x) FROM v       -- ds/dx is treated as 0
+```
+
+That is defensible relational semantics and a real trap, so ddx refuses the
+worst case rather than quietly dropping the term: referencing a computed CTE
+alias as a non-`wrt` term raises `ProjectionBoundary` and tells you to
+differentiate inside the CTE instead. Differentiating *with respect to* such an
+alias is fine — every occurrence is then the differentiation leaf, and
+`grad(s * s, s)` is exactly `2s`.
+
+## Development
+
+```bash
+pip install maturin pytest
+maturin develop --uv
+python -m pytest tests/
+```

ddxdb-0.1.0/crates/ddx-core/CHANGELOG.md

@@ -0,0 +1,189 @@
+# Changelog
+
+All notable changes to `ddx-core` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Entries below the first release are maintained automatically by
+[release-plz](https://release-plz.dev/).
+
+## [Unreleased]
+
+## [0.2.1](https://github.com/xqlsystems/ddx/compare/ddx-core-v0.2.0...ddx-core-v0.2.1) - 2026-08-09
+
+### Fixed
+
+- **`grad(abs(u), x)` reported a zero gradient for a row whose value was NULL.**
+  The derivative of `abs` is emitted as a `CASE` on the sign of `u`, and SQL
+  comparisons are three-valued: against NULL they are NULL, not false. A row with
+  no value therefore answered *none* of the branches and fell through to `ELSE`,
+  which returned `0`:
+
+  ```
+  x = [1.0, NULL, 3.0]   grad(abs(x), x)  ->  [1.0, 0.0, 1.0]
+  ```
+
+  **Who is affected.** Anyone differentiating an expression containing `abs` over
+  data that has gaps — on any engine; this was not engine-specific. The failure
+  is silent and the value is plausible, which is what makes it worth upgrading
+  for: a zero gradient is indistinguishable from a parameter that genuinely does
+  not move, so in a training loop a hole in the batch reads as a converged
+  weight. Expressions without `abs` were never affected, because arithmetic
+  propagates NULL on its own.
+
+  **What changed in the output.** The emitted `CASE` now states the kink as its
+  own condition and reserves `ELSE` for "no comparison answered":
+
+  ```sql
+  -- before
+  CASE WHEN u > 0 THEN 1.0 WHEN u < 0 THEN -1.0 ELSE 0.0 END
+  -- after
+  CASE WHEN u > 0 THEN 1.0 WHEN u < 0 THEN -1.0 WHEN u = 0 THEN 0.0
+       ELSE CAST(NULL AS DOUBLE) END
+  ```
+
+  The pinned convention `abs'(0) = 0` is unchanged, and every non-NULL input
+  gives the same answer as before ([#60](https://github.com/xqlsystems/ddx/pull/60)).
+
+- **The same `CASE` came back as `DECIMAL` on DuckDB.** Its branches were bare
+  literals, which DuckDB types `DECIMAL(2,1)`, so `grad(abs(x), x)` was the one
+  derivative arriving in a different type — with different arithmetic under it —
+  from everything else ddx emits. The typed `ELSE` above fixes the whole
+  expression at `DOUBLE` ([#60](https://github.com/xqlsystems/ddx/pull/60)).
+
+### Added
+
+- `Ddx::unary_rule_names()` and `RuleRegistry::unary_names()` — the unary
+  function names the engine can differentiate, read from the rule registry and
+  including any added with `register`. Useful for deciding whether to hand ddx an
+  expression at all; note that a name being present does not by itself make an
+  *expression* differentiable, since the surrounding constructs matter too, so
+  catching the typed error remains the general answer. **Requires 0.2.1**
+  ([#60](https://github.com/xqlsystems/ddx/pull/60)).
+
+## [0.2.0](https://github.com/xqlsystems/ddx/compare/ddx-core-v0.1.3...ddx-core-v0.2.0) - 2026-08-09
+
+### Added
+
+- **`IdentCasing` gained two policies, for engines the existing two describe
+  incorrectly.** `IdentCasing` says how a dialect folds identifiers before ddx
+  compares them, and it offered only "fold unquoted to lowercase, quoted keeps
+  case" (Postgres, DataFusion) and "fold everything" (DuckDB). Two families of
+  engine fit neither:
+
+  - `IdentCasing::FoldUnquotedUpper` — unquoted identifiers fold to *uppercase*,
+    quoted keep case (Snowflake, Oracle). The same shape as `FoldUnquoted` with
+    the opposite target, which is not a cosmetic difference: bare `X` names the
+    column `"X"` here and `"x"` there.
+  - `IdentCasing::FoldNone` — nothing folds; `x` and `X` are different columns
+    (ClickHouse).
+
+  **Who is affected.** Anyone differentiating SQL aimed at Snowflake, Oracle or
+  ClickHouse while passing `FoldUnquoted`, which was the closest available
+  choice. The consequence was silent: the `wrt` column stopped matching its own
+  occurrences and the derivative came back `0`, or — worse, on the upper-folding
+  engines — matched the *other* column and returned a confident wrong nonzero
+  value. Nothing changes for existing `FoldUnquoted` or `FoldAll` callers; the
+  keys those two produce are unchanged ([#58](https://github.com/xqlsystems/ddx/pull/58)).
+
+### Changed
+
+- **BREAKING: `IdentCasing` is now `#[non_exhaustive]`.** Code outside this crate
+  that matches on it exhaustively must add a wildcard arm:
+
+  ```rust
+  match casing {
+      IdentCasing::FoldUnquoted => ...,
+      IdentCasing::FoldAll => ...,
+      _ => ...,               // now required
+  }
+  ```
+
+  Constructing and comparing variants is unaffected. More engines than these
+  four families exist, and each one found is another variant — marking the enum
+  non-exhaustive now makes those additive rather than a breaking release per
+  engine ([#58](https://github.com/xqlsystems/ddx/pull/58)).
+
+- **BREAKING: `IdentCasing::FoldAll`'s discriminant moved from 1 to 2**, because
+  `FoldUnquotedUpper` was inserted before it to keep the variants grouped by
+  family. This affects only code casting the enum to an integer (`as isize`);
+  the enum has no `#[repr]`, so those values were never guaranteed
+  ([#58](https://github.com/xqlsystems/ddx/pull/58)).
+
+## [0.1.3](https://github.com/xqlsystems/ddx/compare/ddx-core-v0.1.2...ddx-core-v0.1.3) - 2026-08-08
+
+### Other
+
+- *(ddx-core)* skip points where a divisor has cancelled to rounding noise ([#56](https://github.com/xqlsystems/ddx/pull/56))
+
+## [0.1.2](https://github.com/xqlsystems/ddx/compare/ddx-core-v0.1.1...ddx-core-v0.1.2) - 2026-08-08
+
+### Fixed
+
+- **Rendering a derivative could re-associate it, producing a wrong number in
+  valid SQL.** A derivative whose right operand bound as tightly as its parent
+  lost its parentheses: `a * (b / c)` was written as `a * b / c`, which reads
+  back as `(a * b) / c`. The two agree in exact arithmetic and diverge without
+  bound as `c` approaches zero, so a result could be off by any amount — the
+  continuous fuzz caught one wrong by twenty-four orders of magnitude
+  ([#53](https://github.com/xqlsystems/ddx/pull/53)).
+
+  **Who is affected.** Anyone who takes the *text* of a derivative and reparses
+  it — `differentiate_sql`, or `rewrite_sql` output fed to an engine, which is
+  the normal path. Derivatives consumed as an `Expr` in memory were never
+  affected, because nothing reparsed them. The trigger needs a quotient inside a
+  product or a nested quotient, which the quotient and chain rules build
+  routinely, so upgrading is worthwhile even if you have not seen a bad value:
+  the error is silent and only large where a denominator is near zero.
+
+  Emitted SQL now carries a few more parentheses on same-precedence chains.
+  Nothing else about the derivatives changed.
+
+## [0.1.1](https://github.com/xqlsystems/ddx/compare/ddx-core-v0.1.0...ddx-core-v0.1.1) - 2026-08-08
+
+### Added
+
+- `power` with a constant base or exponent now accepts one written as a *cast*
+  literal — `power(x, CAST(3 AS DOUBLE))` differentiates where it previously
+  returned `NotImplemented`. A cast to a numeric type is recognised as the
+  constant it wraps, which matters because query engines inject these: type
+  coercion rewrites `power(x, 3)` over a `DOUBLE` column into
+  `power(CAST(x AS DOUBLE), CAST(3 AS DOUBLE))` before ddx ever sees it. Casts
+  to non-numeric types are still not constants (`CAST(1 AS VARCHAR)` is the
+  string `'1'`).
+- `ddx_core::test_utils`, behind the off-by-default `test-utils` feature: the
+  expression generator, reference interpreter, numeric conditioning gates and
+  failure reporter that `ddx-core`'s own property suite runs on. Exposed so that
+  crates building on `ddx-core` can fuzz against the *same* generator rather
+  than inventing their own. Test support, not API — **semver-exempt**, and
+  compiled only when you turn the feature on, so a default build of `ddx-core`
+  is byte-for-byte unaffected by it.
+
+### Notes
+
+- The engine itself is unchanged: no differentiation rule was added, removed or
+  altered, and every derivative `ddx-core` emitted at 0.1.0 it still emits.
+- This release accompanies the first real `ddx-datafusion` adapter
+  ([#49](https://github.com/xqlsystems/ddx/pull/49)), which is not yet published.
+
+## [0.1.0] - 2026-07-26
+
+### Added
+
+- Initial release: the v1 scalar differentiation engine (design.md Milestone 0).
+- `Ddx` — the engine object: `rewrite_sql` (the whole `grad`/`jvp` marker path,
+  byte-identical outside the marker), `explain` (preview a rewrite without
+  running it), `differentiate` / `jvp` / `differentiate_sql` (the lower-level
+  "calculus compiler" surface), and `register` for user-defined rules.
+- Per-dialect identifier folding (`Ddx::for_datafusion()` / `for_duckdb()`) and
+  an extensible, name-keyed rule registry.
+- Differentiation surface: `+ - * /`; the unary chain rule for the trig /
+  inverse-trig / exp / log / hyperbolic set plus `abs`; `power` with a constant
+  base or exponent; higher-order via nesting; through-aggregate via linearity.
+  Unsupported constructs are typed errors with actionable guidance — never a
+  silently-wrong number.
+- Depends on `sqlparser` only (pinned `=0.62.0`, re-exported as
+  `ddx_core::sqlparser`).
+
+[Unreleased]: https://github.com/xqlsystems/ddx/compare/ddx-core-v0.1.0...HEAD
+[0.1.0]: https://github.com/xqlsystems/ddx/releases/tag/ddx-core-v0.1.0

ddxdb-0.1.0/crates/ddx-core/Cargo.toml

@@ -0,0 +1,34 @@
+[package]
+name = "ddx-core"
+description = "Engine-neutral symbolic differentiation of SQL scalar expressions: `grad` & `jvp`."
+# Versioned independently of the workspace (the scaffold crates stay at the
+# workspace 0.0.0). This is the first publishable crate; release-plz manages
+# bumps from here (SemVer). See CONTRIBUTING.md → Releases.
+version = "0.2.1"
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+authors.workspace = true
+rust-version.workspace = true
+readme = "README.md"
+keywords = ["sql", "autograd", "differentiation", "datafusion", "duckdb"]
+categories = ["mathematics", "database"]
+
+[dependencies]
+# ddx-core re-exports `sqlparser` (see lib.rs) so downstream adapters can't
+# accidentally link a mismatched version. This is the *only* non-trivial
+# dependency of the core, by design.
+sqlparser = { workspace = true }
+
+[features]
+# The shared simulation harness (`ddx_core::test_utils`): generator, reference
+# interpreter, conditioning gates, failure reporter. Off by default so it never
+# ships in a normal build; enabled by every crate that fuzzes, so they all
+# generate the *same* expressions. Semver-exempt — it is test support, not API.
+test-utils = []
+
+[dev-dependencies]
+# ddx-core's own integration tests need the harness too, and an integration test
+# does not inherit its crate's features. A self dev-dependency is the standard
+# way to say "build me again, with this feature, for my own tests".
+ddx-core = { path = ".", features = ["test-utils"] }

ddxdb-0.1.0/crates/ddx-core/README.md

@@ -0,0 +1,64 @@
+# ddx-core
+
+Engine-neutral symbolic differentiation of SQL scalar expressions — the v1
+core of [`ddx`](https://github.com/xqlsystems/ddx), "autograd for composable
+databases." Write calculus directly in SQL and let the engine evaluate the
+derivative per row (the relational equivalent of `jax.vmap(jax.grad(f))`):
+
+```sql
+SELECT i, grad(x * y, x) AS dfdx, grad(x * y, y) AS dfdy FROM g
+```
+
+`grad`/`jvp` are **markers**, not row functions: they carry a differentiation
+request through parsing and are always rewritten away *before* execution.
+
+```rust
+use ddx_core::Ddx;
+use ddx_core::sqlparser::dialect::GenericDialect;
+
+let ddx = Ddx::new();
+let out = ddx.rewrite_sql("SELECT grad(sin(x), x) AS d FROM t", &GenericDialect {})?;
+assert_eq!(out, "SELECT (cos(x)) AS d FROM t");
+```
+
+The engine differentiates [`sqlparser::ast::Expr`](https://docs.rs/sqlparser)
+directly — the AST *is* the IR, there is no bespoke representation. The primary 
+dependency is `sqlparser`, **re-exported** as `ddx_core::sqlparser`
+so downstream adapters cannot link a mismatched version.
+
+## What it supports
+
+`+ - * /`; the unary chain rule for the trig / inverse-trig / exp / log /
+hyperbolic set plus `abs`; `power` with a constant base or exponent;
+higher-order via nesting; through-aggregate via linearity
+(`AVG(grad(loss, theta))`). Custom unary rules are registrable
+(`ddx.register("myfn", rule)` — the rule supplies `f'(u)`, the engine applies
+the chain rule). Anything else is a typed `DiffError`, never a silently-wrong
+number.
+
+Scalar `vjp` is deliberately **not** here: the name is reserved for the
+query-level reverse-mode operation in `ddx-ad` (design.md §3.6, §4).
+
+## Correctness properties worth knowing
+
+- **Identifier folding is per-dialect** (`Ddx::for_datafusion()` vs
+  `Ddx::for_duckdb()`): unquoted identifiers always fold case; DuckDB folds
+  quoted ones too. `grad(Temp*Temp, temp)` matches.
+- **Ambiguity is a hard error, not a guess**: a `wrt` that can't be pinned
+  syntactically (`grad(a.x*b.x, x)`) errors rather than differentiating the
+  wrong column.
+- **`div` forces floating-point division** (`CAST(<numerator> AS DOUBLE)`), so
+  integer columns don't silently truncate the derivative.
+- **0/1-folding follows JAX's `Zero`-tangent convention** and differs from
+  unfolded SQL only on NULL-bearing rows (documented, tested).
+
+See [`../../docs/design.md`](../../docs/design.md) §3 for the full rationale and
+the decision log (`F#`/`G#`) behind each of these.
+
+## Status
+
+M0 (the scalar core) — implemented. The per-engine adapters (`ddx-datafusion`,
+`ddx-duckdb`), the Python wheel (`ddxdb`), and the query-level v2 engine
+(`ddx-ad`) are later milestones; see the design doc's §8.
+
+Licensed under Apache-2.0.