ferro-orm 0.16.3__tar.gz → 0.17.0__tar.gz

{ferro_orm-0.16.3 → ferro_orm-0.17.0}/CHANGELOG.md

@@ -1,6 +1,35 @@
 # CHANGELOG
 
 
+## v0.17.0 (2026-07-18)
+
+### Documentation
+
+- Design existence tests (.exists()) and uniform ~ negation
+  ([`c68a477`](https://github.com/syn54x/ferro-orm/commit/c68a47780cd5fe6d8ecfcb4f7e0f9c8ec2b798fe))
+
+- **query**: Document universal ~ negation and three-valued logic
+  ([`6061d66`](https://github.com/syn54x/ferro-orm/commit/6061d66e96c99f089339f7a4a83b9424101da8be))
+
+### Features
+
+- **query**: Bare .exists() on reverse FK — existence-test tracer bullet
+  ([#319](https://github.com/syn54x/ferro-orm/pull/319),
+  [`2538e06`](https://github.com/syn54x/ferro-orm/commit/2538e06b217e449d10dd564687f5ca3581d5d08d))
+
+- **query**: Existence-test error surfaces and docs — the feature's edges
+  ([`be88aed`](https://github.com/syn54x/ferro-orm/commit/be88aed35f0975f9333bf0dabacaffc8a82f8f34))
+
+- **query**: M2M existence tests — the two-hop correlation path
+  ([`336b529`](https://github.com/syn54x/ferro-orm/commit/336b5298d0e7beca8231452655544fcc7a15ad6a))
+
+- **query**: Scoped existence tests — inner predicates, nesting, cross-scope guard
+  ([`df11625`](https://github.com/syn54x/ferro-orm/commit/df11625b90e01d293f4863bec8afafb9110a1ac3))
+
+- **query**: Uniform predicate negation — prefix ~ as a NOT wire node
+  ([`bfa3126`](https://github.com/syn54x/ferro-orm/commit/bfa3126914b5a1b5d93a65ee3fe2f066bb314b1f))
+
+
 ## v0.16.3 (2026-07-16)
 
 ### Bug Fixes

{ferro_orm-0.16.3 → ferro_orm-0.17.0}/CONTEXT.md

@@ -56,6 +56,10 @@ _Avoid_: Join inference, nested filter, path lookup, string path
 The ordered sequence of forward-FK hops a traversal walks (`account`, or `account → owner`). A path is the identity of a join: the same path referenced anywhere in a query is one join, and distinct paths to the same model are distinct joins. Left-join requests apply to a whole path.
 _Avoid_: Join alias, lookup chain, dotted path string
 
+**Existence test**:
+The only predicate form on a reverse or many-to-many relation — `t.lines.exists(...)` — asking whether at least one related row exists, optionally scoped by a full inner predicate over the related model. Renders as a correlated EXISTS; the result stays root-shaped (shape-preserving query), so it composes with any other predicate, ordering, and paging. Reverse relations are *tested*, never *traversed*: traversal remains a forward-FK concept.
+_Avoid_: membership filter, semi-join filter, reverse traversal, subquery filter, `.any()`
+
 **Shape-preserving query**:
 The invariant that filtering and ordering never change what a query returns — a query over Transaction yields Transaction instances regardless of which relations its predicates traverse. Only an explicit projection operation may change the result shape.
 _Avoid_: Implicit projection, row narrowing

{ferro_orm-0.16.3 → ferro_orm-0.17.0}/Cargo.lock

@@ -327,7 +327,7 @@ dependencies = [
 
 [[package]]
 name = "ferro"
-version = "0.16.3"
+version = "0.17.0"
 dependencies = [
  "chrono",
  "dashmap",
@@ -412,9 +412,9 @@ dependencies = [
 
 [[package]]
 name = "futures"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8b147ee9d1f6d097cef9ce628cd2ee62288d963e16fb287bd9286455b241382d"
+checksum = "a88cf1f829d945f548cf8fec32c61b1f202b6d93b45848602fc02af4b12ad218"
 dependencies = [
  "futures-channel",
  "futures-core",
@@ -427,9 +427,9 @@ dependencies = [
 
 [[package]]
 name = "futures-channel"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "07bbe89c50d7a535e539b8c17bc0b49bdb77747034daa8087407d655f3f7cc1d"
+checksum = "262590f4fe6afeb0bc83be1daa64e52657fe185690a958af7f3ad0e92085c5ae"
 dependencies = [
  "futures-core",
  "futures-sink",
@@ -437,15 +437,15 @@ dependencies = [
 
 [[package]]
 name = "futures-core"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7e3450815272ef58cec6d564423f6e755e25379b217b0bc688e295ba24df6b1d"
+checksum = "2cd50c473c80f6d7c3670a752354b8e569b1a7cbfdc0419ec88e5edad85e0dc7"
 
 [[package]]
 name = "futures-executor"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "baf29c38818342a3b26b5b923639e7b1f4a61fc5e76102d4b1981c6dc7a7579d"
+checksum = "6754879cc9f2c66f88c6e5c35344bb0bdb0708b0352b1201815667c7eabc7458"
 dependencies = [
  "futures-core",
  "futures-task",
@@ -465,15 +465,15 @@ dependencies = [
 
 [[package]]
 name = "futures-io"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cecba35d7ad927e23624b22ad55235f2239cfa44fd10428eecbeba6d6a717718"
+checksum = "4577ecaa3c4f96589d473f679a71b596316f6641bc350038b962a5daf0085d7a"
 
 [[package]]
 name = "futures-macro"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e835b70203e41293343137df5c0664546da5745f82ec9b84d40be8336958447b"
+checksum = "2d6d3cde68c518367be28956066ddfef33813991b77a55005a69dae04bf3b10b"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -482,21 +482,21 @@ dependencies = [
 
 [[package]]
 name = "futures-sink"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c39754e157331b013978ec91992bde1ac089843443c49cbc7f46150b0fad0893"
+checksum = "e34418ac499d6305c2fb5ad0ed2f6ac998c5f8ca209b4510f7f94242c647e307"
 
 [[package]]
 name = "futures-task"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "037711b3d59c33004d3856fbdc83b99d4ff37a24768fa1be9ce3538a1cde4393"
+checksum = "b231ed28831efb4a61a08580c4bc233ec56bc009f4cd8f52da2c3cb97df0c109"
 
 [[package]]
 name = "futures-util"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "389ca41296e6190b48053de0321d02a77f32f8a5d2461dd38762c0593805c6d6"
+checksum = "a77a90a256fce34da66415271e30f94ee91c57b04b8a2c042d9cf3220179deaa"
 dependencies = [
  "futures-channel",
  "futures-core",
@@ -1045,9 +1045,9 @@ checksum = "b4596b6d070b27117e987119b4dac604f3c58cfb0b191112e24771b2faeac1a6"
 
 [[package]]
 name = "portable-atomic"
-version = "1.13.1"
+version = "1.14.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49"
+checksum = "3d20d5497ef88037a52ff98267d066e7f11fcc5e99bbfbd58a42336193aacec3"
 
 [[package]]
 name = "potential_utf"
@@ -1771,9 +1771,9 @@ checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
 
 [[package]]
 name = "tokio"
-version = "1.52.3"
+version = "1.53.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8fc7f01b389ac15039e4dc9531aa973a135d7a4135281b12d7c1bc79fd57fffe"
+checksum = "d988bcd52dbe076d3d46903332f58c912b87a2c49b1428419a5845154762ffee"
 dependencies = [
  "bytes",
  "libc",
@@ -1788,9 +1788,9 @@ dependencies = [
 
 [[package]]
 name = "tokio-macros"
-version = "2.7.0"
+version = "2.7.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "385a6cb71ab9ab790c5fe8d67f1645e6c450a7ce006a33de03daa956cf70a496"
+checksum = "6328af13490e73a9b4694030fafd93f8c8c6a9dede33e821c3fc63eddf8042ba"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -1989,14 +1989,14 @@ version = "0.26.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "521bc38abb08001b01866da9f51eb7c5d647a19260e00054a8c7fd5f9e57f7a9"
 dependencies = [
- "webpki-roots 1.0.8",
+ "webpki-roots 1.0.9",
 ]
 
 [[package]]
 name = "webpki-roots"
-version = "1.0.8"
+version = "1.0.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bf85cb06032201fa7c6f829d7db5a7e5aa45bcc0655327713065f6f0576731bf"
+checksum = "7dcd9d09a39985f5344844e66b0c530a33843579125f23e21e9f0f220850f22a"
 dependencies = [
  "rustls-pki-types",
 ]

{ferro_orm-0.16.3 → ferro_orm-0.17.0}/Cargo.toml

@@ -3,7 +3,7 @@ members = ["crates/ferro-schema-ir", "crates/ferro-ddl-lowering", "crates/ferro-
 
 [package]
 name = "ferro"
-version = "0.16.3"
+version = "0.17.0"
 edition = "2024"
 readme = "README.md"
 

{ferro_orm-0.16.3 → ferro_orm-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferro-orm
-Version: 0.16.3
+Version: 0.17.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: alembic>=1.18.1 ; extra == 'alembic'
 Requires-Dist: sqlalchemy>=2.0.46 ; extra == 'alembic'

{ferro_orm-0.16.3 → ferro_orm-0.17.0}/crates/ferro-schema-ir/src/lib.rs

@@ -137,13 +137,15 @@ pub struct SchemaCheck {
 /// Query IR: filter, sort, pagination, joins, materialization plan, and
 /// optional M2M join context.
 ///
-/// `ir_version: 5` (unconditional, no earlier version emitted anywhere —
-/// #269, #278, #285, #292). `joins` is required and always present (`[]` when
-/// the query traverses no relation); every leaf and `order_by` entry carries a
-/// `path` (required, `[]` = root model); `materialization` is required — the
-/// plan travels with the query as data (ADR-0007), never inferred from a
-/// column list. v5 gives `record` fields expression sources: a field carries
-/// either a `column` + `path` or an `expr` (#292, ADR-0009).
+/// `ir_version: 7` (unconditional, no earlier version emitted anywhere —
+/// #269, #278, #285, #292, #310, #314). `joins` is required and always
+/// present (`[]` when the query traverses no relation); every leaf and
+/// `order_by` entry carries a `path` (required, `[]` = root model);
+/// `materialization` is required — the plan travels with the query as data
+/// (ADR-0007), never inferred from a column list. v5 gave `record` fields
+/// expression sources (#292, ADR-0009); v6 gave predicate trees the
+/// recursive `not` node kind (uniform negation, #310, ADR-0008); v7 adds the
+/// recursive `exists` node kind (existence tests, #314, ADR-0007).
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 pub struct QueryIrPayload {
     /// Model class name the query targets.
@@ -333,7 +335,9 @@ pub struct QueryOrderBy {
     pub path: Vec<String>,
 }
 
-/// Predicate tree node in query IR (leaf comparison or compound AND/OR).
+/// Predicate tree node in query IR: leaf comparison, compound AND/OR, a
+/// recursive NOT wrapping any child (uniform negation, v6, ADR-0008), or a
+/// recursive existence test over a reverse/M2M relation (v7, ADR-0007).
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 #[serde(tag = "node_kind")]
 pub enum QueryNode {
@@ -360,6 +364,37 @@ pub enum QueryNode {
         /// Right subtree.
         right: Box<QueryNode>,
     },
+    /// Uniform negation (`~`, ADR-0008): SQL `NOT (...)` over the child.
+    /// Fully general — the child may be any node kind, at any depth; there
+    /// are no per-operator negative forms on the wire.
+    #[serde(rename = "not")]
+    Not {
+        /// The negated subtree.
+        child: Box<QueryNode>,
+    },
+    /// Existence test on a reverse or M2M relation (ADR-0007): a correlated
+    /// `EXISTS (SELECT 1 ...)` at every cardinality. Carries no negation
+    /// flag — NOT EXISTS is the `not` node over this one.
+    #[serde(rename = "exists")]
+    Exists {
+        /// Correlation hop path in the `joins`-section hop-fact shape: one
+        /// hop for a reverse FK (`FROM child WHERE child.fk = root.pk`), two
+        /// for M2M (join table, then target). The first hop's table is the
+        /// subquery FROM, correlated to the enclosing scope's alias;
+        /// remaining hops render as inner joins inside the subquery.
+        hops: Vec<QueryJoinHop>,
+        /// Ordinary inner condition tree over the relation's target model
+        /// (`[]` = bare test). May itself contain `exists`/`not` nodes —
+        /// nesting is recursion, not a second mechanism.
+        #[serde(rename = "where")]
+        where_clause: Vec<QueryNode>,
+        /// Forward-traversal joins the inner tree references (#315),
+        /// rendered INSIDE the subquery as inner joins (ADR-0006 traversal
+        /// semantics are unchanged there; `left_join` has no inner-lambda
+        /// spelling). Absent on the wire when empty — pinned bytes.
+        #[serde(default, skip_serializing_if = "Vec::is_empty")]
+        joins: Vec<QueryJoin>,
+    },
 }
 
 /// Typed literal or parameter value on the RHS of a leaf predicate.
@@ -438,7 +473,7 @@ mod tests {
     #[test]
     fn query_fixture_roundtrip() {
         let fixture =
-            include_str!("../../../tests/fixtures/ir_vectors/query_user_compound_v5.json");
+            include_str!("../../../tests/fixtures/ir_vectors/query_user_compound_v7.json");
         let parsed: serde_json::Value =
             serde_json::from_str(fixture).expect("query fixture must parse");
         let ir = parsed
@@ -456,12 +491,224 @@ mod tests {
         assert_eq!(encoded, ir, "query round-trip must not drift");
     }
 
+    #[test]
+    fn query_not_leaf_fixture_roundtrip() {
+        // The not-over-leaf golden vector (#312, ADR-0008): uniform negation
+        // travels as one recursive `not` node wrapping its child — here a
+        // leaf `IN` comparison (the NOT IN spelling) — and must survive a
+        // deserialize/serialize round-trip without drift.
+        let fixture =
+            include_str!("../../../tests/fixtures/ir_vectors/query_user_not_leaf_v7.json");
+        let parsed: serde_json::Value =
+            serde_json::from_str(fixture).expect("query not-leaf fixture must parse");
+        let ir = parsed
+            .get("ir")
+            .cloned()
+            .expect("fixture must contain ir envelope");
+        let envelope: IrEnvelope<QueryIrPayload> =
+            serde_json::from_value(ir.clone()).expect("query not-leaf IR must deserialize");
+        // The wire carries a `not` node whose child is the IN leaf.
+        match &envelope.payload.where_clause[0] {
+            QueryNode::Not { child } => match child.as_ref() {
+                QueryNode::Leaf { operator, .. } => assert_eq!(operator, "IN"),
+                other => panic!("not child must be the IN leaf, got {other:?}"),
+            },
+            other => panic!("where[0] must be a not node, got {other:?}"),
+        }
+        let encoded = serde_json::to_value(&envelope).expect("query not-leaf IR must serialize");
+        assert_eq!(encoded, ir, "query not-leaf round-trip must not drift");
+    }
+
+    #[test]
+    fn query_not_compound_fixture_roundtrip() {
+        // The not-over-compound golden vector (#313, ADR-0008): `~` wraps an
+        // OR compound whole — no De Morgan expansion on the wire — and must
+        // survive a deserialize/serialize round-trip without drift.
+        let fixture =
+            include_str!("../../../tests/fixtures/ir_vectors/query_user_not_compound_v7.json");
+        let parsed: serde_json::Value =
+            serde_json::from_str(fixture).expect("query not-compound fixture must parse");
+        let ir = parsed
+            .get("ir")
+            .cloned()
+            .expect("fixture must contain ir envelope");
+        let envelope: IrEnvelope<QueryIrPayload> =
+            serde_json::from_value(ir.clone()).expect("query not-compound IR must deserialize");
+        match &envelope.payload.where_clause[0] {
+            QueryNode::Not { child } => match child.as_ref() {
+                QueryNode::Compound { operator, .. } => assert_eq!(operator, "OR"),
+                other => panic!("not child must be the OR compound, got {other:?}"),
+            },
+            other => panic!("where[0] must be a not node, got {other:?}"),
+        }
+        let encoded =
+            serde_json::to_value(&envelope).expect("query not-compound IR must serialize");
+        assert_eq!(encoded, ir, "query not-compound round-trip must not drift");
+    }
+
+    #[test]
+    fn query_exists_fixture_roundtrip() {
+        // The bare 1-hop existence-test golden vector (#314, ADR-0007): an
+        // `exists` node carries its correlation hop path plus an empty inner
+        // condition tree, and must survive a deserialize/serialize
+        // round-trip without drift.
+        let fixture =
+            include_str!("../../../tests/fixtures/ir_vectors/query_account_exists_v7.json");
+        let parsed: serde_json::Value =
+            serde_json::from_str(fixture).expect("query exists fixture must parse");
+        let ir = parsed
+            .get("ir")
+            .cloned()
+            .expect("fixture must contain ir envelope");
+        let envelope: IrEnvelope<QueryIrPayload> =
+            serde_json::from_value(ir.clone()).expect("query exists IR must deserialize");
+        match &envelope.payload.where_clause[0] {
+            QueryNode::Exists {
+                hops, where_clause, ..
+            } => {
+                assert_eq!(hops.len(), 1);
+                assert_eq!(hops[0].relation, "transactions");
+                assert_eq!(hops[0].from_column, "id");
+                assert_eq!(hops[0].to_table, "transaction");
+                assert_eq!(hops[0].to_column, "account_id");
+                assert!(where_clause.is_empty(), "bare test carries no inner tree");
+            }
+            other => panic!("where[0] must be an exists node, got {other:?}"),
+        }
+        let encoded = serde_json::to_value(&envelope).expect("query exists IR must serialize");
+        assert_eq!(encoded, ir, "query exists round-trip must not drift");
+    }
+
+    #[test]
+    fn query_not_exists_fixture_roundtrip() {
+        // NOT EXISTS on the wire is the ordinary `not` node over an `exists`
+        // node — the exists node carries no negation flag (ADR-0008
+        // composition; #314).
+        let fixture =
+            include_str!("../../../tests/fixtures/ir_vectors/query_owner_not_exists_v7.json");
+        let parsed: serde_json::Value =
+            serde_json::from_str(fixture).expect("query not-exists fixture must parse");
+        let ir = parsed
+            .get("ir")
+            .cloned()
+            .expect("fixture must contain ir envelope");
+        let envelope: IrEnvelope<QueryIrPayload> =
+            serde_json::from_value(ir.clone()).expect("query not-exists IR must deserialize");
+        match &envelope.payload.where_clause[0] {
+            QueryNode::Not { child } => match child.as_ref() {
+                QueryNode::Exists { hops, .. } => assert_eq!(hops[0].relation, "accounts"),
+                other => panic!("not child must be the exists node, got {other:?}"),
+            },
+            other => panic!("where[0] must be a not node, got {other:?}"),
+        }
+        let encoded = serde_json::to_value(&envelope).expect("query not-exists IR must serialize");
+        assert_eq!(encoded, ir, "query not-exists round-trip must not drift");
+    }
+
+    #[test]
+    fn query_scoped_exists_fixture_roundtrip() {
+        // The scoped existence-test golden vector (#315): the inner tree is
+        // an ordinary condition tree, and a traversed inner leaf's hop facts
+        // ride the exists node's own `joins` section (rendered INSIDE the
+        // subquery). Must survive a deserialize/serialize round-trip.
+        let fixture =
+            include_str!("../../../tests/fixtures/ir_vectors/query_account_scoped_exists_v7.json");
+        let parsed: serde_json::Value =
+            serde_json::from_str(fixture).expect("query scoped-exists fixture must parse");
+        let ir = parsed
+            .get("ir")
+            .cloned()
+            .expect("fixture must contain ir envelope");
+        let envelope: IrEnvelope<QueryIrPayload> =
+            serde_json::from_value(ir.clone()).expect("query scoped-exists IR must deserialize");
+        match &envelope.payload.where_clause[0] {
+            QueryNode::Exists {
+                hops,
+                where_clause,
+                joins,
+            } => {
+                assert_eq!(hops.len(), 1);
+                assert_eq!(where_clause.len(), 1);
+                assert_eq!(joins.len(), 1);
+                assert_eq!(joins[0].join_type, "inner");
+                assert_eq!(joins[0].path[0].relation, "account");
+            }
+            other => panic!("where[0] must be an exists node, got {other:?}"),
+        }
+        let encoded =
+            serde_json::to_value(&envelope).expect("query scoped-exists IR must serialize");
+        assert_eq!(encoded, ir, "query scoped-exists round-trip must not drift");
+    }
+
+    #[test]
+    fn query_nested_exists_fixture_roundtrip() {
+        // Nested exists-in-exists (#315): depth is recursion, not a second
+        // mechanism, and the bare inner node omits `joins` entirely (absent,
+        // not empty — pinned wire bytes via skip_serializing_if).
+        let fixture =
+            include_str!("../../../tests/fixtures/ir_vectors/query_owner_nested_exists_v7.json");
+        let parsed: serde_json::Value =
+            serde_json::from_str(fixture).expect("query nested-exists fixture must parse");
+        let ir = parsed
+            .get("ir")
+            .cloned()
+            .expect("fixture must contain ir envelope");
+        let envelope: IrEnvelope<QueryIrPayload> =
+            serde_json::from_value(ir.clone()).expect("query nested-exists IR must deserialize");
+        match &envelope.payload.where_clause[0] {
+            QueryNode::Exists { where_clause, .. } => match &where_clause[0] {
+                QueryNode::Exists { hops, joins, .. } => {
+                    assert_eq!(hops[0].relation, "transactions");
+                    assert!(joins.is_empty(), "bare nested test carries no joins");
+                }
+                other => panic!("inner where[0] must be an exists node, got {other:?}"),
+            },
+            other => panic!("where[0] must be an exists node, got {other:?}"),
+        }
+        let encoded =
+            serde_json::to_value(&envelope).expect("query nested-exists IR must serialize");
+        assert_eq!(encoded, ir, "query nested-exists round-trip must not drift");
+    }
+
+    #[test]
+    fn query_m2m_exists_fixture_roundtrip() {
+        // The two-hop M2M existence-test golden vector (#316): the SAME
+        // exists node, a two-hop correlation path — join table first, then
+        // the target — with the scoped inner tree over the target model.
+        // Must survive a deserialize/serialize round-trip without drift.
+        let fixture =
+            include_str!("../../../tests/fixtures/ir_vectors/query_user_m2m_exists_v7.json");
+        let parsed: serde_json::Value =
+            serde_json::from_str(fixture).expect("query m2m-exists fixture must parse");
+        let ir = parsed
+            .get("ir")
+            .cloned()
+            .expect("fixture must contain ir envelope");
+        let envelope: IrEnvelope<QueryIrPayload> =
+            serde_json::from_value(ir.clone()).expect("query m2m-exists IR must deserialize");
+        match &envelope.payload.where_clause[0] {
+            QueryNode::Exists {
+                hops, where_clause, ..
+            } => {
+                assert_eq!(hops.len(), 2, "M2M correlates through two hops");
+                assert_eq!(hops[0].to_table, "tag_users");
+                assert_eq!(hops[0].to_column, "user_id");
+                assert_eq!(hops[1].from_column, "tag_id");
+                assert_eq!(hops[1].to_table, "tag");
+                assert_eq!(where_clause.len(), 1);
+            }
+            other => panic!("where[0] must be an exists node, got {other:?}"),
+        }
+        let encoded = serde_json::to_value(&envelope).expect("query m2m-exists IR must serialize");
+        assert_eq!(encoded, ir, "query m2m-exists round-trip must not drift");
+    }
+
     #[test]
     fn query_traversal_fixture_roundtrip() {
         // Multi-hop `joins` section + path-carrying leaves must survive a
         // deserialize/serialize round-trip without drift (#270 wire stability).
         let fixture = include_str!(
-            "../../../tests/fixtures/ir_vectors/query_transaction_traversal_v5.json"
+            "../../../tests/fixtures/ir_vectors/query_transaction_traversal_v7.json"
         );
         let parsed: serde_json::Value =
             serde_json::from_str(fixture).expect("query traversal fixture must parse");
@@ -487,7 +734,7 @@ mod tests {
         // deserialize/serialize round-trip without drift, and the join_type
         // tokens must reach Rust exactly as written on the wire.
         let fixture =
-            include_str!("../../../tests/fixtures/ir_vectors/query_transaction_left_join_v5.json");
+            include_str!("../../../tests/fixtures/ir_vectors/query_transaction_left_join_v7.json");
         let parsed: serde_json::Value =
             serde_json::from_str(fixture).expect("query left_join fixture must parse");
         let ir = parsed
@@ -513,7 +760,7 @@ mod tests {
         // payload — predicate, order, limit, and a two-field record plan —
         // survives a deserialize/serialize round-trip without drift.
         let fixture =
-            include_str!("../../../tests/fixtures/ir_vectors/query_transaction_record_v5.json");
+            include_str!("../../../tests/fixtures/ir_vectors/query_transaction_record_v7.json");
         let parsed: serde_json::Value =
             serde_json::from_str(fixture).expect("query record fixture must parse");
         let ir = parsed
@@ -712,7 +959,7 @@ mod tests {
         // identity) — survives a deserialize/serialize round-trip without
         // drift. No group keys: the whole result collapses to one record.
         let fixture = include_str!(
-            "../../../tests/fixtures/ir_vectors/query_transaction_global_aggregate_v5.json"
+            "../../../tests/fixtures/ir_vectors/query_transaction_global_aggregate_v7.json"
         );
         let parsed: serde_json::Value =
             serde_json::from_str(fixture).expect("global aggregate fixture must parse");
@@ -750,7 +997,7 @@ mod tests {
         // joins section included — survives a deserialize/serialize
         // round-trip without drift.
         let fixture = include_str!(
-            "../../../tests/fixtures/ir_vectors/query_transaction_traversed_record_v5.json"
+            "../../../tests/fixtures/ir_vectors/query_transaction_traversed_record_v7.json"
         );
         let parsed: serde_json::Value =
             serde_json::from_str(fixture).expect("query traversed record fixture must parse");
@@ -788,7 +1035,7 @@ mod tests {
         // a deserialize/serialize round-trip without drift. GROUP BY does not
         // travel: the renderer derives it from the non-expr fields (ADR-0009).
         let fixture = include_str!(
-            "../../../tests/fixtures/ir_vectors/query_transaction_aggregate_v5.json"
+            "../../../tests/fixtures/ir_vectors/query_transaction_aggregate_v7.json"
         );
         let parsed: serde_json::Value =
             serde_json::from_str(fixture).expect("query aggregate fixture must parse");
@@ -856,7 +1103,7 @@ mod tests {
         // payload — root predicate, empty `joins`, and a one-path instances
         // plan — survives a deserialize/serialize round-trip without drift.
         let fixture =
-            include_str!("../../../tests/fixtures/ir_vectors/query_transaction_include_v5.json");
+            include_str!("../../../tests/fixtures/ir_vectors/query_transaction_include_v7.json");
         let parsed: serde_json::Value =
             serde_json::from_str(fixture).expect("query include fixture must parse");
         let ir = parsed

ferro_orm-0.17.0/docs/adr/0007-reverse-relations-tested-not-traversed.md

@@ -0,0 +1,62 @@
+# Reverse relations are tested, not traversed
+
+A reverse (BackRef) or many-to-many relation appears in a query predicate in
+exactly one form: the **existence test** — `t.lines.exists(...)`, optionally
+scoped by an inner predicate over the related model, negated with `~`. It
+renders as a correlated `EXISTS` subquery at every cardinality (one-to-one
+BackRefs included) and for every relation kind (reverse FK and M2M, the latter
+correlating through the join table). The result stays root-shaped: an
+existence test never multiplies root rows and composes with any other
+predicate, ordering, and paging.
+
+The proxy for a reverse relation exposes `.exists()` and nothing else. Column
+access (`t.lines.category_id`), comparison (`t.transfer_out != None`), and
+`in_` all raise at build time with the supported spelling in the message.
+There is deliberately no implicit path traversal onto reverse edges — the
+spelling sketched by the originating external PRDs (#307/#308, from Pinch).
+Implicit traversal has an unanswerable grouping ambiguity: in
+`(t.lines.a == 1) & (t.lines.b == 2)` nothing visible says whether one child
+row must match both conditions or some child may match each. Django chose
+implicit and the resulting confusion is a documented hazard of that API. The
+explicit combinator makes grouping the user's choice —
+`t.lines.exists(lambda l: A & B)` versus
+`t.lines.exists(A-test) & t.lines.exists(B-test)` — both spellable, both
+unambiguous. This is the same determinism-over-friendliness ground on which
+ADR-0006 rejected auto-LEFT.
+
+The inner predicate is a full ferro predicate over the related model: same
+operators, forward traversal (rendered as joins inside the subquery, ADR-0006
+semantics unchanged), and nested existence tests to arbitrary depth. What it
+may not do (v1) is reference any scope other than its own parameter —
+cross-scope column comparison is rejected at build time and tracked as a
+possible future extension.
+
+Rejected alternatives:
+
+- **`.any()`/`.has()` cardinality split (SQLAlchemy)** — two names for one
+  mechanism, and call sites break when a FK's `unique=` changes. One concept,
+  one verb: `.exists()` at every cardinality.
+- **`in_(single-column ProjectedQuery)`** — declined, not deferred. The
+  workloads it serves are existence-test workloads; it forces callers to
+  hand-correlate on id columns and leaks the join column into every call site.
+- **LEFT JOIN + IS NOT NULL specialization for unique BackRefs** — safe but a
+  second render path with no user-visible benefit; planners already rewrite
+  correlated EXISTS into semi-joins. May become an invisible planner-side
+  optimization later if measured.
+- **`!= None` / `== None` sugar for bare existence** — forward `== None`
+  desugars to IS NULL on a shadow column that physically lives on the root
+  table (ADR-0006); a reverse relation has no root-side column, so the sugar
+  would be silent implicit traversal.
+
+## Consequences
+
+- The glossary term "Relation traversal" stays forward-FK-only, and that
+  narrowness is now load-bearing rather than incidental.
+- `include()` (population) and `.exists()` (membership) remain distinct axes;
+  BackRef population is still a separate future mechanism.
+- The wire IR gains one recursive node kind for the existence test, carrying a
+  correlation hop path (1 hop for reverse FK, 2 for M2M) — the Rust renderer
+  handles both with one loop, so M2M support is test surface, not mechanism.
+- `left_join()` on a reverse edge stays rejected (it would reopen the
+  "join never multiplies root rows" property) but the error now names
+  `.exists()` as the supported spelling.