feat(objectql): filtered roll-up summary fields (#1868)

`summaryOperations` gains an optional `filter` — a query `where`
FilterCondition evaluated against each child row — so a roll-up `summary`
field aggregates only the matching children instead of the whole child
collection. This is the piece the cross-object rollup templates were
missing: it lets a single child object feed several distinct parent totals
(e.g. content_publication.total_signups vs total_clicks over one engagement
child, or procurement_order.received_amount summing only received receipt
lines in a 3-way match).

The engine ANDs the predicate with the parent-FK match when it recomputes,
and because the whole filtered aggregate is re-run on every child
insert/update/delete, a child that moves in or out of the predicate
(a status change) keeps the parent current with no extra wiring. Operator
and compound filter forms work too.

Purely additive: omitting `filter` aggregates every child exactly as before.

- spec: add `summaryOperations.filter` (FilterCondition) + tests; regen
  reference doc; note the sub-key in the liveness ledger
- objectql: thread the filter through SummaryDescriptor / buildSummaryIndex /
  recomputeSummaries; tests for filtered sum/count, $in/$gte compounds, and
  in/out-of-filter recompute on update & delete
- docs: document `filter` in field-types.mdx and the objectstack-data
  relationships skill; fix a stale non-canonical summary example in that skill

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HbK4FqcHwp9jSwdhTtxYuC

Author: claude

.changeset/summary-rollup-filter.md

@@ -0,0 +1,32 @@
+---
+'@objectstack/spec': minor
+'@objectstack/objectql': minor
+---
+
+feat(objectql): roll-up `summary` fields can filter which child rows they aggregate (#1868)
+
+`summaryOperations` gains an optional `filter` — a query `where` FilterCondition
+evaluated against each child row, so a summary aggregates only the matching
+children instead of the whole collection. This is what lets a single child object
+feed several distinct parent totals, which the cross-object rollup templates need:
+
+```typescript
+// One `engagement` child → distinct filtered totals.
+total_signups: {
+  type: 'summary',
+  summaryOperations: { object: 'engagement', field: 'id', function: 'count', filter: { type: 'signup' } },
+}
+// Sum only received receipt lines (3-way match).
+received_amount: {
+  type: 'summary',
+  summaryOperations: { object: 'procurement_receipt', field: 'amount', function: 'sum', filter: { status: 'received' } },
+}
+```
+
+The engine ANDs the predicate with the parent-FK match when it recomputes, and
+because the whole filtered aggregate is re-run on every child write, a child that
+moves in or out of the predicate (e.g. a status change) keeps the parent current
+with no extra wiring. Operator and compound forms work too
+(`filter: { type: { $in: ['signup', 'trial'] }, amount: { $gte: 100 } }`).
+
+Purely additive: omitting `filter` aggregates every child exactly as before.

content/docs/data-modeling/field-types.mdx

@@ -447,6 +447,7 @@ Roll-up summary from child records.
 | `summaryOperations.field` | `string` | **required** | Child field to aggregate; ignored for `count` |
 | `summaryOperations.function` | `enum` | **required** | `count`, `sum`, `avg`, `min`, or `max` |
 | `summaryOperations.relationshipField` | `string` | auto | Child FK back to the parent when it cannot be inferred |
+| `summaryOperations.filter` | `FilterCondition` | — | Only child rows matching this `where` predicate are aggregated |
 
 ```typescript
 {
@@ -462,6 +463,32 @@ Roll-up summary from child records.
 }
 ```
 
+Add a `filter` to aggregate only a subset of children — this is how one child
+object feeds several different totals. The engine ANDs the predicate with the
+parent-FK match and recomputes on the child's next write, so a row moving in or
+out of the filter (a status change) keeps the parent current:
+
+```typescript
+// Sum only received receipt lines (3-way match), not every line.
+{
+  name: 'received_amount',
+  type: 'summary',
+  summaryOperations: {
+    object: 'procurement_receipt',
+    field: 'amount',
+    function: 'sum',
+    filter: { status: 'received' },
+  },
+}
+
+// One `engagement` child → distinct totals, differentiated only by the filter.
+{
+  name: 'total_signups',
+  type: 'summary',
+  summaryOperations: { object: 'engagement', field: 'id', function: 'count', filter: { type: 'signup' } },
+}
+```
+
 ### `autonumber`
 Auto-incrementing number with format template.
 

content/docs/references/data/field.mdx

@@ -132,7 +132,7 @@ const result = Address.parse(data);
 | **allowCreate** | `boolean` | optional | Allow inline quick-create from the record picker: when no match exists the user can create a record from the typed text (optimistic dataSource.create with the display field). Best for simple objects whose only required field is the display field. |
 | **expression** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | optional | Formula expression (CEL). e.g. F`record.amount * 0.1` |
 | **returnType** | `Enum<'number' \| 'text' \| 'boolean' \| 'date'>` | optional | Inferred value type of a formula field (number/text/boolean/date) |
-| **summaryOperations** | `{ object: string; field: string; function: Enum<'count' \| 'sum' \| 'min' \| 'max' \| 'avg'>; relationshipField?: string }` | optional | Roll-up summary definition. The engine recomputes the value when child records are inserted/updated/deleted. |
+| **summaryOperations** | `{ object: string; field: string; function: Enum<'count' \| 'sum' \| 'min' \| 'max' \| 'avg'>; relationshipField?: string; … }` | optional | Roll-up summary definition. The engine recomputes the value when child records are inserted/updated/deleted. |
 | **language** | `string` | optional | Programming language for syntax highlighting (e.g., javascript, python, sql) |
 | **step** | `number` | optional | Step increment for slider (default: 1) |
 | **currencyConfig** | `{ precision?: integer; currencyMode?: Enum<'dynamic' \| 'fixed'>; defaultCurrency?: string }` | optional | Configuration for currency field type |

packages/objectql/src/engine.ts

@@ -283,6 +283,12 @@ interface SummaryDescriptor {
   fn: 'count' | 'sum' | 'min' | 'max' | 'avg';
   /** Child field aggregated (unused for count). */
   sourceField: string;
+  /**
+   * Optional predicate (a query `where` FilterCondition) restricting which child
+   * rows are aggregated. ANDed with the parent-FK match when the aggregate runs.
+   * Undefined ⇒ aggregate every child of the parent.
+   */
+  filter?: Record<string, unknown>;
 }
 
 export class ObjectQL implements IDataEngine {
@@ -1841,8 +1847,14 @@ export class ObjectQL implements IDataEngine {
           }
         }
         if (!fkField) continue; // can't resolve the relationship — skip
+        // Optional per-summary predicate: only child rows matching it are
+        // aggregated (e.g. sum receipts where { status: 'received' }). ANDed with
+        // the parent-FK match at recompute time. Ignore a non-object filter.
+        const filter = so.filter && typeof so.filter === 'object' && !Array.isArray(so.filter)
+          ? so.filter as Record<string, unknown>
+          : undefined;
         const list = index.get(childObject) ?? [];
-        list.push({ parentObject: parent.name, summaryField, fkField, fn, sourceField: so.field });
+        list.push({ parentObject: parent.name, summaryField, fkField, fn, sourceField: so.field, filter });
         index.set(childObject, list);
       }
     }
@@ -1882,8 +1894,12 @@ export class ObjectQL implements IDataEngine {
           // aggregate/update) with backoff — a network blip here used to leave
           // the parent summary silently stale (framework#3147).
           await withTransientRetry(async () => {
+            // AND the parent-FK match with the optional per-summary filter so
+            // only matching child rows are aggregated (e.g. received receipts).
+            const fkMatch = { [desc.fkField]: parentId };
+            const where = desc.filter ? { $and: [fkMatch, desc.filter] } : fkMatch;
             const rows = await this.aggregate(childObject, {
-              where: { [desc.fkField]: parentId },
+              where,
               aggregations: [{
                 function: desc.fn,
                 ...(desc.fn === 'count' ? {} : { field: desc.sourceField }),

packages/objectql/src/summary-rollup.test.ts

@@ -14,9 +14,35 @@ function makeDriver() {
     if (!s) { s = new Map(); stores.set(o, s); }
     return s;
   };
+  // Minimal FilterCondition matcher: implicit equality, a few operators, and the
+  // logical `$and`/`$or`/`$not` the engine emits when a summary carries a filter
+  // (`{ $and: [{ fk: parentId }, <filter> }] }`). Enough to exercise the merge.
+  const checkOp = (value: any, cond: any): boolean => {
+    if (cond === null || typeof cond !== 'object' || Array.isArray(cond) || cond instanceof Date) {
+      return value === cond;
+    }
+    return Object.entries(cond).every(([op, target]: [string, any]) => {
+      switch (op) {
+        case '$eq': return value === target;
+        case '$ne': return value !== target;
+        case '$gt': return value > target;
+        case '$gte': return value >= target;
+        case '$lt': return value < target;
+        case '$lte': return value <= target;
+        case '$in': return Array.isArray(target) && target.includes(value);
+        case '$nin': return Array.isArray(target) && !target.includes(value);
+        default: return true;
+      }
+    });
+  };
   const matches = (row: any, where: any): boolean => {
     if (!where || typeof where !== 'object') return true;
-    return Object.entries(where).every(([k, v]) => row?.[k] === v);
+    return Object.entries(where).every(([k, v]: [string, any]) => {
+      if (k === '$and') return (v as any[]).every((w) => matches(row, w));
+      if (k === '$or') return (v as any[]).some((w) => matches(row, w));
+      if (k === '$not') return !matches(row, v);
+      return checkOp(row?.[k], v);
+    });
   };
   let n = 0;
   const driver: any = {
@@ -123,3 +149,91 @@ describe('roll-up summary fields', () => {
     expect(parent(b.id).line_total).toBe(3);
   });
 });
+
+describe('roll-up summary fields with a filter predicate', () => {
+  let engine: ObjectQL;
+  let storeFor: ReturnType<typeof makeDriver>['storeFor'];
+
+  beforeEach(async () => {
+    engine = new ObjectQL();
+    const d = makeDriver();
+    storeFor = d.storeFor;
+    engine.registerDriver(d.driver, true);
+    await engine.init();
+    // A publication rolls up ONE child object (`engagement`) into several totals,
+    // each differentiated only by a `filter` — the shape the issue's
+    // content_publication.total_views/clicks/signups fields need.
+    engine.registry.registerObject({
+      name: 'publication',
+      fields: {
+        name: { type: 'text' },
+        total_events: { type: 'summary', summaryOperations: { object: 'engagement', field: 'id', function: 'count' } },
+        total_signups: { type: 'summary', summaryOperations: { object: 'engagement', field: 'id', function: 'count', filter: { type: 'signup' } } },
+        total_revenue: { type: 'summary', summaryOperations: { object: 'engagement', field: 'amount', function: 'sum', filter: { type: 'signup' } } },
+        premium_signups: { type: 'summary', summaryOperations: { object: 'engagement', field: 'id', function: 'count', filter: { type: { $in: ['signup', 'trial'] }, amount: { $gte: 100 } } } },
+      },
+    } as any);
+    engine.registry.registerObject({
+      name: 'engagement',
+      fields: {
+        type: { type: 'text' },
+        amount: { type: 'number' },
+        publication: { type: 'master_detail', reference: 'publication' },
+      },
+    } as any);
+  });
+
+  const pub = (id: string) => storeFor('publication').get(id);
+
+  it('aggregates only the child rows matching the filter', async () => {
+    const p = await engine.insert('publication', { name: 'POST-1' });
+    await engine.insert('engagement', { publication: p.id, type: 'view', amount: 0 });
+    await engine.insert('engagement', { publication: p.id, type: 'view', amount: 0 });
+    await engine.insert('engagement', { publication: p.id, type: 'signup', amount: 30 });
+    await engine.insert('engagement', { publication: p.id, type: 'signup', amount: 50 });
+
+    expect(pub(p.id).total_events).toBe(4);     // unfiltered
+    expect(pub(p.id).total_signups).toBe(2);    // filter: type == signup
+    expect(pub(p.id).total_revenue).toBe(80);   // sum(amount) where type == signup
+  });
+
+  it('honours operator/compound filters ($in + $gte)', async () => {
+    const p = await engine.insert('publication', { name: 'POST-2' });
+    await engine.insert('engagement', { publication: p.id, type: 'signup', amount: 40 });   // amount < 100
+    await engine.insert('engagement', { publication: p.id, type: 'signup', amount: 150 });  // matches
+    await engine.insert('engagement', { publication: p.id, type: 'trial', amount: 200 });   // matches
+    await engine.insert('engagement', { publication: p.id, type: 'view', amount: 999 });    // wrong type
+
+    expect(pub(p.id).premium_signups).toBe(2);
+  });
+
+  it('recomputes when a child moves in/out of the filter via an update', async () => {
+    const p = await engine.insert('publication', { name: 'POST-3' });
+    const e = await engine.insert('engagement', { publication: p.id, type: 'view', amount: 25 });
+    expect(pub(p.id).total_signups).toBe(0);
+    expect(pub(p.id).total_revenue).toBe(0);
+
+    // Reclassify the same row as a signup — it now enters the filtered rollups.
+    await engine.update('engagement', { id: e.id, type: 'signup' });
+    expect(pub(p.id).total_signups).toBe(1);
+    expect(pub(p.id).total_revenue).toBe(25);
+
+    // And back out again.
+    await engine.update('engagement', { id: e.id, type: 'view' });
+    expect(pub(p.id).total_signups).toBe(0);
+    expect(pub(p.id).total_revenue).toBe(0);
+  });
+
+  it('recomputes the filtered rollup when a matching child is deleted', async () => {
+    const p = await engine.insert('publication', { name: 'POST-4' });
+    const e = await engine.insert('engagement', { publication: p.id, type: 'signup', amount: 60 });
+    await engine.insert('engagement', { publication: p.id, type: 'view', amount: 0 });
+    expect(pub(p.id).total_signups).toBe(1);
+    expect(pub(p.id).total_revenue).toBe(60);
+
+    await engine.delete('engagement', { where: { id: e.id } });
+    expect(pub(p.id).total_signups).toBe(0);
+    expect(pub(p.id).total_revenue).toBe(0);
+    expect(pub(p.id).total_events).toBe(1); // the unfiltered count still sees the view
+  });
+});

packages/spec/liveness/field.json

@@ -65,7 +65,7 @@
     "summaryOperations": {
       "status": "live",
       "evidence": "packages/objectql/src/engine.ts",
-      "note": "rollup {object,field,function,relationshipField}."
+      "note": "rollup {object,field,function,relationshipField,filter}. `filter` (a query `where` FilterCondition) is read by buildSummaryIndex and ANDed with the parent-FK match in recomputeSummaries, so one child object can feed several filtered totals."
     },
     "requiredWhen": {
       "status": "live",

packages/spec/src/data/field.test.ts

@@ -382,7 +382,7 @@ describe('FieldSchema', () => {
 
     it('should accept all summary functions', () => {
       const functions = ['count', 'sum', 'min', 'max', 'avg'] as const;
-      
+
       functions.forEach(fn => {
         const field: Field = {
           name: 'test_summary',
@@ -398,6 +398,40 @@ describe('FieldSchema', () => {
         expect(() => FieldSchema.parse(field)).not.toThrow();
       });
     });
+
+    it('should accept a summary field with a filter predicate', () => {
+      const field: Field = {
+        name: 'received_amount',
+        label: 'Received Amount',
+        type: 'summary',
+        summaryOperations: {
+          object: 'procurement_receipt',
+          field: 'amount',
+          function: 'sum',
+          filter: { status: 'received' },
+        },
+      };
+
+      const parsed = FieldSchema.parse(field);
+      expect(parsed.summaryOperations?.filter).toEqual({ status: 'received' });
+    });
+
+    it('should accept a filtered count with operator syntax and an explicit relationship field', () => {
+      const field: Field = {
+        name: 'signup_count',
+        label: 'Signups',
+        type: 'summary',
+        summaryOperations: {
+          object: 'engagement',
+          field: 'id',
+          function: 'count',
+          relationshipField: 'publication_id',
+          filter: { type: { $in: ['signup', 'trial'] } },
+        },
+      };
+
+      expect(() => FieldSchema.parse(field)).not.toThrow();
+    });
   });
 
   describe('Security and Visibility', () => {

packages/spec/src/data/field.zod.ts

@@ -3,6 +3,7 @@
 import { z } from 'zod';
 import { SystemIdentifierSchema } from '../shared/identifiers.zod';
 import { ExpressionInputSchema } from '../shared/expression.zod';
+import { FilterConditionSchema } from './filter.zod';
 
 /**
  * Field Type Enum
@@ -402,6 +403,19 @@ export const FieldSchema = lazySchema(() => z.object({
     field: z.string().describe('Field on child object to aggregate (ignored for count)'),
     function: z.enum(['count', 'sum', 'min', 'max', 'avg']).describe('Aggregation function to apply'),
     relationshipField: z.string().optional().describe('FK field on the child pointing back to this parent. Auto-detected from the child\'s lookup/master_detail field referencing this object when omitted; set explicitly only when the child has more than one such reference.'),
+    /**
+     * Optional predicate that restricts WHICH child rows are aggregated — a
+     * FilterCondition (the same object DSL as a query `where`), evaluated against
+     * each child row. Omit to aggregate every child. This is what lets several
+     * summaries roll up the SAME child object into different totals — e.g.
+     * `content_publication.total_signups` = count of engagement rows where
+     * `{ type: 'signup' }` vs `total_clicks` where `{ type: 'click' }`, or
+     * `procurement_order.received_amount` = sum of receipt lines where
+     * `{ status: 'received' }`. The engine ANDs it with the parent-FK match, so
+     * a child moving in or out of the predicate (a status change) recomputes the
+     * parent on its next write like any other child update.
+     */
+    filter: FilterConditionSchema.optional().describe("Predicate restricting which child rows are aggregated (a query `where` FilterCondition, e.g. { status: 'received' } or { type: { $in: ['signup','trial'] } }). Omit to aggregate all children. Lets one child object feed multiple filtered roll-ups."),
   }).optional().describe('Roll-up summary definition. The engine recomputes the value when child records are inserted/updated/deleted.'),
 
   /** Enhanced Field Type Configurations */

skills/objectstack-data/rules/relationships.md

@@ -63,9 +63,11 @@ export default ObjectSchema.create({
     invoice_number: { type: 'text', required: true },
     total: {
       type: 'summary',
-      reference: 'invoice_line_item',
-      summaryType: 'sum',
-      summaryField: 'amount',
+      summaryOperations: {
+        object: 'invoice_line_item',
+        field: 'amount',
+        function: 'sum',
+      },
     },
   }
 });
@@ -181,6 +183,8 @@ transaction as the write, so it's consistent and never summed on the client).
     // relationshipField: 'invoice' // optional; auto-detected from the child's
                                      // master_detail/lookup field referencing
                                      // this parent when omitted
+    // filter: { status: 'received' } // optional; only children matching this
+                                       // `where` predicate are aggregated
   },
 }
 ```
@@ -189,6 +193,16 @@ Empty collections roll up to `0` for `count`/`sum`, `null` for `min`/`max`/`avg`
 Pairs naturally with inline editing (below): the parent total updates atomically
 as line items are saved.
 
+Add `filter` (a query `where` FilterCondition) to aggregate only a **subset** of
+the children — this is how a single child object feeds several different totals.
+For example one `engagement` child yields `total_signups`
+(`filter: { type: 'signup' }`) and `total_clicks` (`filter: { type: 'click' }`),
+and a `procurement_receipt` child yields `received_amount`
+(`function: 'sum', filter: { status: 'received' }`). The predicate is ANDed with
+the parent-FK match; a child moving in or out of it (e.g. a status change)
+recomputes the parent on its next write like any other child update. Operator
+and compound forms work too (`filter: { type: { $in: ['signup','trial'] } }`).
+
 ## Inline Editing (Master-Detail Entry)
 
 Declare inline editing **on the relationship**, in the data model — not in a form