ferro-orm 0.15.0__tar.gz → 0.16.0__tar.gz

{ferro_orm-0.15.0 → ferro_orm-0.16.0}/CHANGELOG.md

@@ -1,6 +1,37 @@
 # CHANGELOG
 
 
+## v0.16.0 (2026-07-13)
+
+### Chores
+
+- ADR-0009 aggregate projections + output-alias/traversed-projection/aggregate-projection glossary
+  ([`51b8c0c`](https://github.com/syn54x/ferro-orm/commit/51b8c0c5fef2d383561b0127028ad5e7eb5bbbc3))
+
+### Documentation
+
+- Aggregation guide, projection reference, typing page
+  ([#296](https://github.com/syn54x/ferro-orm/pull/296),
+  [`44230c5`](https://github.com/syn54x/ferro-orm/commit/44230c55b53544788210f0664dc2a32634409839))
+
+### Features
+
+- Global aggregates — count/sum/avg/min/max ([#294](https://github.com/syn54x/ferro-orm/pull/294),
+  [`1679e44`](https://github.com/syn54x/ferro-orm/commit/1679e44399b8ecc9f47a4f416dbf9aa821173b16))
+
+- Grouped aggregates, order_by rules, verb guardrails
+  ([#295](https://github.com/syn54x/ferro-orm/pull/295),
+  [`2408ad7`](https://github.com/syn54x/ferro-orm/commit/2408ad7ae91cf6e7024e7297764191967596e869))
+
+- Traversed projection + output aliases ([#293](https://github.com/syn54x/ferro-orm/pull/293),
+  [`1e73e2a`](https://github.com/syn54x/ferro-orm/commit/1e73e2a8f53a4d56d3caaa38a754166023e4c361))
+
+### Refactoring
+
+- QueryIR v5 — the expr record-field shape ([#292](https://github.com/syn54x/ferro-orm/pull/292),
+  [`dc779d0`](https://github.com/syn54x/ferro-orm/commit/dc779d0e1184e6c87e19872302a045c3f36b8e5f))
+
+
 ## v0.15.0 (2026-07-11)
 
 ### Chores

{ferro_orm-0.15.0 → ferro_orm-0.16.0}/CONTEXT.md

@@ -80,6 +80,18 @@ _Avoid_: Eager-loaded field, select_related, prefetched attribute, joined attrib
 A query's declaration of what its result columns become: complete root instances (every query today), a projected record of named fields, or — in the future — a populated instance graph. Every query carries exactly one plan; the plan travels with the query rather than being inferred from its column list.
 _Avoid_: Select list, projection spec, hydration mode flag
 
+**Aggregate projection**:
+A projection containing at least one aggregate field. Each group collapses to exactly one projected record: every non-aggregate field is a group key, so grouping is derived from the projection and never declared separately. With no non-aggregate fields, the whole result collapses to a single record. Grouping collapses rows — bucketing complete instances by a key ("partitioning") is a different, client-side operation and is not grouping.
+_Avoid_: Group-by query, summary query, rollup, partition
+
+**Traversed projection**:
+A projected record field whose source column lives across a forward-FK relation path (`select(lambda t: t.account.name)`). Projection traversal narrows exactly like predicate traversal (ADR-0006). Unaliased, the field takes the bare leaf column name; two selected fields sharing an output name is a build-time error, resolved with an output alias.
+_Avoid_: Nested select, join column, related-field pull
+
+**Output alias**:
+A user-chosen name for one field of a projected record, given as the key in a dict-returning selector (`select(lambda t: {"account_name": t.account.name})`). Aliases name output fields only — never joins or tables; the relation path remains the sole join identity.
+_Avoid_: Column alias, AS label, join alias
+
 **Provisional registration**:
 The per-model state installed when a class body finishes executing — enough for runtime codec and PK metadata, but relationships may still be pending and the modelset is not yet authoritative for DDL.
 _Avoid_: Import-time registration, partial registry

{ferro_orm-0.15.0 → ferro_orm-0.16.0}/Cargo.lock

@@ -327,7 +327,7 @@ dependencies = [
 
 [[package]]
 name = "ferro"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "chrono",
  "dashmap",
@@ -1905,9 +1905,9 @@ checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
 
 [[package]]
 name = "uuid"
-version = "1.23.4"
+version = "1.23.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bf80a72845275afea99e7f2b434723d3bc7e38470fcd1c7ed39a599c73319a53"
+checksum = "ea5fab0d6c3c01ae70085a09cb03d4c7a1d6314e2b3e075392783396d724ca0a"
 dependencies = [
  "getrandom 0.4.3",
  "js-sys",
@@ -2329,6 +2329,6 @@ dependencies = [
 
 [[package]]
 name = "zmij"
-version = "1.0.21"
+version = "1.0.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
+checksum = "bd2f034a4bebf216c9e4b7083603e024cf930873fd67830cfb083c9fa33129d9"

{ferro_orm-0.15.0 → ferro_orm-0.16.0}/Cargo.toml

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

{ferro_orm-0.15.0 → ferro_orm-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferro-orm
-Version: 0.15.0
+Version: 0.16.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.15.0 → ferro_orm-0.16.0}/crates/ferro-schema-ir/src/lib.rs

@@ -137,13 +137,13 @@ pub struct SchemaCheck {
 /// Query IR: filter, sort, pagination, joins, materialization plan, and
 /// optional M2M join context.
 ///
-/// `ir_version: 4` (unconditional, no earlier version emitted anywhere —
-/// #269, #278, #285). `joins` is required and always present (`[]` when the
-/// query traverses no relation); every leaf and `order_by` entry carries a
+/// `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. v4 gives the `instances` kind its field shape: `paths` of
-/// hop facts (#285).
+/// column list. v5 gives `record` fields expression sources: a field carries
+/// either a `column` + `path` or an `expr` (#292, ADR-0009).
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 pub struct QueryIrPayload {
     /// Model class name the query targets.
@@ -200,23 +200,103 @@ pub enum Materialization {
 
 /// One projected field in a [`Materialization::Record`] plan.
 ///
-/// `name` is declared separately from the source `column`, the field carries a
-/// relation `path`, and may later carry an `expr` instead of a column — so
-/// output aliases, traversed projection, and aggregations (#282) extend this
-/// shape additively without reshaping the v3 contract.
+/// `name` is declared separately from the source, so output aliases are free
+/// (`name` is the alias). A field reads from exactly one source (v5, #292,
+/// ADR-0009): a `column` + relation `path` (plain and traversed projection),
+/// or an `expr` (aggregations) — never both, never neither, enforced at
+/// deserialization via [`RecordFieldWire`]. GROUP BY never travels on the
+/// wire: the renderer derives group keys from the plan — every non-`expr`
+/// field is a key (ADR-0009).
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(try_from = "RecordFieldWire")]
 pub struct RecordField {
     /// Output field name on the projected record.
     pub name: String,
-    /// Source column the value reads from (`name == column` until output
-    /// aliases land with #282).
-    pub column: String,
+    /// Source column the value reads from. `Some` iff `expr` is `None`.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub column: Option<String>,
     /// Relation path from the root model to `column`'s table (`[]` = root
-    /// model; non-empty paths are traversed projection, #282).
+    /// model; non-empty paths are traversed projection, #293). Belongs to the
+    /// `column` arm: an `expr` field carries its traversal on the expression
+    /// itself, so its outer `path` is always `[]`.
     pub path: Vec<String>,
-    /// Reserved: expression source instead of a column (aggregations, #282).
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub expr: Option<Value>,
+    /// Expression source instead of a column (aggregations, #294/#295).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub expr: Option<RecordExpr>,
+}
+
+/// The expression source of an aggregate record field (v5, #292, ADR-0009).
+///
+/// Self-contained on the wire: `fn` travels as data (the closed aggregate
+/// set), and `path` carries the source column's traversal as ordered hop
+/// facts — the same hop shape as the `joins` section — rather than keying
+/// into it.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct RecordExpr {
+    /// Aggregate function applied to `column`.
+    pub r#fn: AggregateFn,
+    /// Source column the aggregate reads from.
+    pub column: String,
+    /// Relation hops from the root model to `column`'s table (`[]` = root
+    /// model), in the `joins`-section hop-fact shape.
+    pub path: Vec<QueryJoinHop>,
+}
+
+/// The closed set of aggregate functions a [`RecordExpr`] may apply
+/// (ADR-0009). Carried as data on the wire; an unknown token fails the strict
+/// parse naming the supported set.
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "lowercase")]
+pub enum AggregateFn {
+    Count,
+    Sum,
+    Avg,
+    Min,
+    Max,
+}
+
+/// Field-wise wire shape backing [`RecordField`] deserialization, so the
+/// exactly-one-source invariant is a parse-time rejection, not a downstream
+/// walker check.
+#[derive(Debug, Deserialize)]
+struct RecordFieldWire {
+    name: String,
+    #[serde(default)]
+    column: Option<String>,
+    path: Vec<String>,
+    #[serde(default)]
+    expr: Option<RecordExpr>,
+}
+
+impl TryFrom<RecordFieldWire> for RecordField {
+    type Error = String;
+
+    fn try_from(wire: RecordFieldWire) -> Result<Self, Self::Error> {
+        match (&wire.column, &wire.expr) {
+            (Some(_), Some(_)) => Err(format!(
+                "record field {:?} carries both `column` and `expr`; \
+                 a field reads from exactly one source",
+                wire.name
+            )),
+            (None, None) => Err(format!(
+                "record field {:?} carries neither `column` nor `expr`; \
+                 a field reads from exactly one source",
+                wire.name
+            )),
+            (None, Some(_)) if !wire.path.is_empty() => Err(format!(
+                "record field {:?} carries an `expr` and a non-empty field \
+                 `path` {:?}; an expression field's traversal travels on \
+                 `expr.path` (hop facts), so its field `path` must be empty",
+                wire.name, wire.path
+            )),
+            _ => Ok(RecordField {
+                name: wire.name,
+                column: wire.column,
+                path: wire.path,
+                expr: wire.expr,
+            }),
+        }
+    }
 }
 
 /// One relation JOIN collected from query-time traversal (#270 lands rendering).
@@ -358,7 +438,7 @@ mod tests {
     #[test]
     fn query_fixture_roundtrip() {
         let fixture =
-            include_str!("../../../tests/fixtures/ir_vectors/query_user_compound_v4.json");
+            include_str!("../../../tests/fixtures/ir_vectors/query_user_compound_v5.json");
         let parsed: serde_json::Value =
             serde_json::from_str(fixture).expect("query fixture must parse");
         let ir = parsed
@@ -381,7 +461,7 @@ mod tests {
         // 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_v4.json"
+            "../../../tests/fixtures/ir_vectors/query_transaction_traversal_v5.json"
         );
         let parsed: serde_json::Value =
             serde_json::from_str(fixture).expect("query traversal fixture must parse");
@@ -407,7 +487,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_v4.json");
+            include_str!("../../../tests/fixtures/ir_vectors/query_transaction_left_join_v5.json");
         let parsed: serde_json::Value =
             serde_json::from_str(fixture).expect("query left_join fixture must parse");
         let ir = parsed
@@ -433,7 +513,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_v4.json");
+            include_str!("../../../tests/fixtures/ir_vectors/query_transaction_record_v5.json");
         let parsed: serde_json::Value =
             serde_json::from_str(fixture).expect("query record fixture must parse");
         let ir = parsed
@@ -474,13 +554,271 @@ mod tests {
         };
         assert_eq!(fields.len(), 2);
         assert_eq!(fields[0].name, "id");
-        assert_eq!(fields[0].column, "id");
+        assert_eq!(fields[0].column.as_deref(), Some("id"));
         assert!(fields[0].path.is_empty());
-        assert!(fields[0].expr.is_none(), "expr is reserved and absent");
+        assert!(fields[0].expr.is_none(), "a column field carries no expr");
         let encoded = serde_json::to_value(&plan).expect("record kind must serialize");
         assert_eq!(encoded, wire, "record round-trip must not drift");
     }
 
+    #[test]
+    fn traversed_record_field_roundtrips() {
+        // v5 (#292): a plain traversed record field — non-empty relation
+        // `path`, a `column`, no `expr` — is the shape the tracer-bullet
+        // slice (#293) consumes. The path stays relation names (it keys into
+        // the `joins` section, like `order_by.path`), not hop facts.
+        let wire = serde_json::json!({
+            "kind": "record",
+            "fields": [
+                {"name": "account_name", "column": "name", "path": ["account"]},
+                {"name": "owner_email", "column": "email",
+                 "path": ["account", "owner"]}
+            ]
+        });
+        let plan: Materialization =
+            serde_json::from_value(wire.clone()).expect("traversed fields must deserialize");
+        let Materialization::Record { fields } = &plan else {
+            panic!("expected Record, got {plan:?}");
+        };
+        assert_eq!(fields[0].path, vec!["account".to_string()]);
+        assert_eq!(fields[1].path.len(), 2);
+        let encoded = serde_json::to_value(&plan).expect("traversed fields must serialize");
+        assert_eq!(encoded, wire, "traversed record round-trip must not drift");
+    }
+
+    #[test]
+    fn record_expr_fields_roundtrip() {
+        // v5 (#292): expression fields — root and traversed sources. `fn`
+        // travels as data; `expr.path` carries hop facts (the `joins`-section
+        // shape), self-contained rather than keying into the joins list.
+        let wire = serde_json::json!({
+            "kind": "record",
+            "fields": [
+                {"name": "acct", "column": "account_id", "path": []},
+                {"name": "total", "path": [],
+                 "expr": {"fn": "sum", "column": "amount", "path": []}},
+                {"name": "avg_balance", "path": [],
+                 "expr": {"fn": "avg", "column": "balance", "path": [
+                     {"relation": "account", "from_column": "account_id",
+                      "to_table": "account", "to_column": "id"}
+                 ]}}
+            ]
+        });
+        let plan: Materialization =
+            serde_json::from_value(wire.clone()).expect("expr fields must deserialize");
+        let Materialization::Record { fields } = &plan else {
+            panic!("expected Record, got {plan:?}");
+        };
+        assert_eq!(fields.len(), 3);
+        // The group-key field is a plain column source.
+        assert_eq!(fields[0].column.as_deref(), Some("account_id"));
+        assert!(fields[0].expr.is_none());
+        // The root aggregate: fn as data, no column, empty hop path.
+        let total = fields[1].expr.as_ref().expect("total must carry an expr");
+        assert!(fields[1].column.is_none());
+        assert_eq!(total.r#fn, AggregateFn::Sum);
+        assert_eq!(total.column, "amount");
+        assert!(total.path.is_empty());
+        // The traversed aggregate: hop facts on the expression itself.
+        let avg = fields[2].expr.as_ref().expect("avg must carry an expr");
+        assert_eq!(avg.r#fn, AggregateFn::Avg);
+        assert_eq!(avg.path.len(), 1);
+        assert_eq!(avg.path[0].relation, "account");
+        assert_eq!(avg.path[0].from_column, "account_id");
+        let encoded = serde_json::to_value(&plan).expect("expr fields must serialize");
+        assert_eq!(encoded, wire, "expr record round-trip must not drift");
+    }
+
+    #[test]
+    fn record_field_with_both_column_and_expr_is_rejected() {
+        // Exactly-one-of is a deserialization invariant (#292): both sources
+        // present fails the strict parse naming the field.
+        let err = serde_json::from_value::<Materialization>(serde_json::json!({
+            "kind": "record",
+            "fields": [{
+                "name": "total", "column": "amount", "path": [],
+                "expr": {"fn": "sum", "column": "amount", "path": []}
+            }]
+        }))
+        .expect_err("both column and expr must fail to deserialize");
+        let msg = err.to_string();
+        assert!(
+            msg.contains("total") && msg.contains("both"),
+            "must name the field and the violation: {msg}"
+        );
+    }
+
+    #[test]
+    fn record_field_with_neither_column_nor_expr_is_rejected() {
+        let err = serde_json::from_value::<Materialization>(serde_json::json!({
+            "kind": "record",
+            "fields": [{"name": "total", "path": []}]
+        }))
+        .expect_err("neither column nor expr must fail to deserialize");
+        let msg = err.to_string();
+        assert!(
+            msg.contains("total") && msg.contains("neither"),
+            "must name the field and the violation: {msg}"
+        );
+    }
+
+    #[test]
+    fn record_expr_with_unknown_fn_is_rejected() {
+        // `fn` is the closed aggregate set (ADR-0009); an unknown token fails
+        // the strict parse naming the bad token and the supported set.
+        let err = serde_json::from_value::<Materialization>(serde_json::json!({
+            "kind": "record",
+            "fields": [{
+                "name": "mid", "path": [],
+                "expr": {"fn": "median", "column": "amount", "path": []}
+            }]
+        }))
+        .expect_err("an unknown aggregate fn must fail to deserialize");
+        let msg = err.to_string();
+        assert!(msg.contains("median"), "must name the bad fn: {msg}");
+        for supported in ["count", "sum", "avg", "min", "max"] {
+            assert!(
+                msg.contains(supported),
+                "must name supported fn {supported:?}: {msg}"
+            );
+        }
+    }
+
+    #[test]
+    fn record_expr_field_with_outer_path_is_rejected() {
+        // An expression field's traversal travels on `expr.path`; a non-empty
+        // field-level `path` next to an `expr` is two contradictory traversal
+        // claims and fails the strict parse.
+        let err = serde_json::from_value::<Materialization>(serde_json::json!({
+            "kind": "record",
+            "fields": [{
+                "name": "avg_balance", "path": ["account"],
+                "expr": {"fn": "avg", "column": "balance", "path": []}
+            }]
+        }))
+        .expect_err("an expr field with a field-level path must fail to deserialize");
+        let msg = err.to_string();
+        assert!(
+            msg.contains("avg_balance") && msg.contains("expr.path"),
+            "must name the field and point at expr.path: {msg}"
+        );
+    }
+
+    #[test]
+    fn query_global_aggregate_fixture_roundtrip() {
+        // The global-aggregate golden vector (#294): an aggregate-only record
+        // plan — count, root sum, and a traversed avg carrying hop facts on
+        // the expression, plus a `joins` entry sharing the avg's path (join
+        // 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"
+        );
+        let parsed: serde_json::Value =
+            serde_json::from_str(fixture).expect("global aggregate 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("global aggregate IR must deserialize");
+        let Materialization::Record { fields } = &envelope.payload.materialization else {
+            panic!(
+                "expected a record plan, got {:?}",
+                envelope.payload.materialization
+            );
+        };
+        assert_eq!(fields.len(), 3);
+        assert!(
+            fields.iter().all(|f| f.expr.is_some()),
+            "a global aggregate plan is aggregate-only"
+        );
+        assert_eq!(
+            fields[0].expr.as_ref().map(|e| e.r#fn),
+            Some(AggregateFn::Count)
+        );
+        let encoded =
+            serde_json::to_value(&envelope).expect("global aggregate IR must serialize");
+        assert_eq!(encoded, ir, "global aggregate round-trip must not drift");
+    }
+
+    #[test]
+    fn query_traversed_record_fixture_roundtrip() {
+        // The traversed-projection golden vector (#293): an aliased root
+        // field, a 1-hop field under a LEFT-marked path, and a 2-hop field
+        // sharing that path's prefix — the full dict-selector wire shape,
+        // 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"
+        );
+        let parsed: serde_json::Value =
+            serde_json::from_str(fixture).expect("query traversed record 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 traversed record IR must deserialize");
+        let Materialization::Record { fields } = &envelope.payload.materialization else {
+            panic!(
+                "expected a record plan, got {:?}",
+                envelope.payload.materialization
+            );
+        };
+        assert_eq!(fields.len(), 3);
+        // The root field is aliased: name and column differ.
+        assert_eq!(fields[0].name, "txn_id");
+        assert_eq!(fields[0].column.as_deref(), Some("id"));
+        // Traversed fields carry relation-name paths keying into `joins`.
+        assert_eq!(fields[1].path, vec!["account".to_string()]);
+        assert_eq!(fields[2].path.len(), 2);
+        assert_eq!(envelope.payload.joins[0].join_type, "left");
+        let encoded =
+            serde_json::to_value(&envelope).expect("query traversed record IR must serialize");
+        assert_eq!(encoded, ir, "query traversed record round-trip must not drift");
+    }
+
+    #[test]
+    fn query_aggregate_fixture_roundtrip() {
+        // The aggregate-projection golden vector (#292): a grouped query's
+        // full payload — a traversed group key sharing its path with the
+        // `joins` section, a root aggregate, a traversed aggregate carrying
+        // hop facts on the expression, and an output-name ORDER BY — survives
+        // 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"
+        );
+        let parsed: serde_json::Value =
+            serde_json::from_str(fixture).expect("query aggregate 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 aggregate IR must deserialize");
+        let Materialization::Record { fields } = &envelope.payload.materialization else {
+            panic!(
+                "expected a record plan, got {:?}",
+                envelope.payload.materialization
+            );
+        };
+        assert_eq!(fields.len(), 3);
+        assert_eq!(fields[0].path, vec!["account".to_string()]);
+        assert_eq!(
+            fields[1].expr.as_ref().map(|e| e.r#fn),
+            Some(AggregateFn::Sum)
+        );
+        assert_eq!(
+            fields[2].expr.as_ref().map(|e| e.path.len()),
+            Some(1),
+            "the traversed aggregate carries its hop facts"
+        );
+        let encoded = serde_json::to_value(&envelope).expect("query aggregate IR must serialize");
+        assert_eq!(encoded, ir, "query aggregate round-trip must not drift");
+    }
+
     #[test]
     fn instances_materialization_roundtrips() {
         // v4 (#285): the `instances` kind carries `paths` — ordered hop-fact
@@ -518,7 +856,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_v4.json");
+            include_str!("../../../tests/fixtures/ir_vectors/query_transaction_include_v5.json");
         let parsed: serde_json::Value =
             serde_json::from_str(fixture).expect("query include fixture must parse");
         let ir = parsed

ferro_orm-0.16.0/docs/adr/0009-aggregate-projections-derived-grouping.md

@@ -0,0 +1,70 @@
+# Aggregate projections: grouping derived from the projection, pinned decode contract, flat record+relation results
+
+Aggregation rides the `record` materialization plan (ADR-0007): aggregate
+fields (`t.amount.sum()` — methods on scalar field proxies; the closed set
+`count/sum/avg/min/max`) land in projected records, and a projection
+containing any aggregate is an **aggregate projection** (`CONTEXT.md`) in
+which every non-aggregate field is a group key — GROUP BY is **derived from
+the projection, never declared**; there is no `group_by()` chainer. Aggregate
+result types are a **pinned cross-backend contract** derived from the source
+column's Python type (`count → int`; `min`/`max` → source type and codec;
+`sum` → source numeric type; `avg` → float for int/float, Decimal for
+Decimal); source families with no portable cross-backend meaning (enum, uuid,
+json, bool) are rejected at build time. Record results that reach across a
+relation are **flat** — traversed projection with output aliases — and
+`include()` × `select()` is rejected permanently (flattened-as-final),
+closing the question ADR-0008 parked with #282.
+
+Decision by owner (2026-07-12), grilling #282 on the partial-materialization
+substrate (#277/#279).
+
+Rejected alternatives:
+
+- **An explicit `group_by()` chainer**: SQL's own rule already forces every
+  bare selected column to be a group key, so a chainer is pure redundancy
+  plus a new error class ("bare column not in group_by") that Postgres
+  rejects at runtime and SQLite answers with an *arbitrary row's value*.
+  Derivation makes the invalid query unwritable and keeps the dict literal
+  the whole story: the record shape determines the grouping. The only
+  expressiveness lost — grouping by an unselected column — can arrive later
+  additively; the reverse (retiring a shipped chainer) could not.
+- **Backend-native result types** (driver passthrough): Postgres `SUM(int8)`
+  and `AVG(int)` are `numeric`; SQLite `sum(int)` is int and `avg` is float —
+  the same query would return different Python types per backend.
+- **Aggregating any column family, letting the DB decide**: `min`/`max` over
+  uuid does not exist on Postgres, and over a native enum silently diverges
+  (definition order vs. SQLite's lexical text order). Where no portable
+  meaning exists, build time is the only honest place to fail.
+- **Nested record+relation results** (`Row(amount=…, account=<Account>)`): a
+  third result shape — part record, part instance — needing its own decode,
+  typing, and identity story, while every concrete need is served flatter and
+  clearer by a traversed, aliased field. Records carry values; instances
+  carry rows.
+- **Coalescing empty aggregates to zero**: "sum of no rows" and "sum of rows
+  totaling zero" are different facts, and zero is the wrong identity for
+  `min`/`max` anyway. SQL's NULL passes through as `None` uniformly
+  (`count → 0`), with no hidden COALESCE.
+
+## Consequences
+
+- The canonical grouped query is one lambda —
+  `select(lambda t: {"acct": t.account_id, "total": t.amount.sum()})` renders
+  `GROUP BY account_id`. Aggregate-only projections collapse to one record
+  (read with `first()`); a grouped query over zero rows returns zero records.
+- GROUP BY never travels on the wire: the renderer derives the keys from the
+  v5 `record` plan (every non-`expr` field), pinned by golden vectors —
+  renderer work, like joins rendering from paths.
+- Aggregate record fields are `T | None` (`count` excepted) — empty-input
+  NULL passes through.
+- `order_by` strings resolve output field names before root columns on a
+  projected query (SQL's own ORDER BY scoping); on an aggregate projection
+  every sort key must be a group key or an aggregate — build-time error, the
+  SQLite arbitrary-row trap made unwritable. `limit()`/`offset()` act on
+  groups.
+- `count()`/`exists()` raise on an aggregate projection with guidance (rows:
+  unprojected query; groups: `len(await q.all())`) — #279's "unaffected by
+  projection" contract is the *plain*-projection rule.
+- `where()` never accepts an aggregate predicate; post-aggregation filtering
+  is `having()` (#291).
+- A left-joined traversed group key yields a `None`-keyed group — "has no
+  relation" is a visible bucket, not a dropped row.