@plumbus/core 0.6.7 → 0.6.8

package/instructions/entities.md

@@ -107,6 +107,31 @@ const total = await ctx.data.User.count({ active: true }, filters);
 
 `findMany` applies `limit`/`offset`/`orderBy`; `count` returns the matching row count over the same filters (so page totals stay correct). `search` uses case-insensitive `ILIKE` (OR across columns), `in` is SQL `IN`, `notEq` is `<>`. Multi-column sort: `orderBy: [{ column: "name", dir: "asc" }, { column: "createdAt", dir: "desc" }]`. Tenant isolation and soft-delete filters are applied automatically.
 
+### Aggregates (SUM / GROUP BY / DISTINCT)
+
+To total, average, or group **in the database** — instead of loading rows and reducing in memory — use `aggregate`. Filtering is identical to `findMany`/`count` (the `query` equality arg plus `dateFilters`/`search`/`in`/`notEq`), and tenant scoping, soft-delete, and encrypted-field guards all apply.
+
+```ts
+// Grand total over a filtered scope — one row, even over zero matches:
+const [totals] = await ctx.data.ProjectCostLedger.aggregate(
+  { projectId },
+  { dateFilters: { recordedAt: { gte: monthStart } }, sum: "cost", count: true },
+);
+totals.sum_cost; // number (empty scope = 0); totals.count // number
+
+// GROUP BY with per-group aggregates, ordered by an aggregate, limited:
+const byProvider = await ctx.data.ProjectCostLedger.aggregate(
+  {},
+  { groupBy: "provider", sum: "cost", count: true, orderBy: "sum_cost", orderDir: "desc", limit: 10 },
+);
+// → [{ provider: "openai", sum_cost: 41.2, count: 318 }, ...]
+
+// COUNT(DISTINCT), min/max/avg also supported:
+await ctx.data.WorkflowStep.aggregate({}, { countDistinct: "projectId" }); // [{ countDistinct_projectId: 7 }]
+```
+
+Result rows (`AggregateRow`) key each `groupBy` column by its value, plus `count` (when `count: true`), `sum_<col>`, `avg_<col>`, `min_<col>`, `max_<col>`, and `countDistinct_<col>` per requested column. `sum_*`, `count`, and `countDistinct_*` are numbers (an empty `SUM` is `0`, not `null`); `avg_*`/`min_*`/`max_*` are `null` over an empty set. Without `groupBy` you always get exactly one grand-total row; with `groupBy`, one row per group that has matching records. `orderBy` may reference a group column or an aggregate alias (e.g. `"sum_cost"`); `limit` is clamped to 1–1000. Requesting neither a group column nor an aggregate throws. Aggregating an `encrypted: true` field is rejected. Add a matching composite index (e.g. `indexes: [["projectId", "recordedAt"]]`) so the aggregate runs as an index scan.
+
 Repositories automatically:
 - Inject `tenantId` from `ctx.auth.tenantId` (if `tenantScoped: true`)
 - Record audit events for mutations

package/instructions/security.md

@@ -64,6 +64,8 @@ Entity fields with `classification: "sensitive"` or `"highly_sensitive"`:
 - Trigger governance warnings if used in AI prompts
 - Can be flagged for encryption at rest (`encrypted: true` + `PLUMBUS_ENCRYPTION_KEY`)
 
+When encryption is enabled, repositories reject `findMany`/`aggregate` filters and aggregate functions on encrypted string columns (ciphertext is not queryable at the SQL layer). See [entities.md](./entities.md#aggregates-sum--group-by--distinct).
+
 **AI prompt scanning** is separate and **opt-in**: configure `aiProviders.security` (or `AI_SECURITY_*` env) to warn/redact/block classified fields in `ctx.ai.*` inputs. Without that config, classification alone does not scan prompts. See `ai.md` § Security.
 
 ### Edit Zones

package/instructions/testing.md

@@ -47,6 +47,35 @@ expect(page1.data.items).not.toEqual(page2.data.items);
 expect(page1.data.total).toBeGreaterThan(page1.data.limit);
 ```
 
+### Aggregate / dashboard capabilities
+
+When testing capabilities that call `aggregate()` (totals, grouped rollups, `COUNT(DISTINCT)`), use `createTestContext()` or `createInMemoryRepository()` — both mirror production aggregate semantics without a database:
+
+- Assert **grand totals** return a single row (even over an empty filter scope, where `SUM` is `0`)
+- Assert **GROUP BY** returns one row per group with the expected `sum_*` / `count` / `countDistinct_*` keys
+- Assert **filters** (`query`, `dateFilters`, `search`, `in`, `notEq`) narrow the scope the same way as `findMany`/`count`
+- Assert **empty scope** for grouped queries returns no rows; ungrouped empty scope returns `[{ sum_*: 0, count: 0 }]`
+
+```ts
+const ctx = createTestContext({
+  data: {
+    Ledger: [
+      { id: "1", provider: "openai", cost: 1.5 },
+      { id: "2", provider: "openai", cost: 2.5 },
+      { id: "3", provider: "anthropic", cost: 3 },
+    ],
+  },
+});
+
+const rows = await ctx.data.Ledger.aggregate(
+  { provider: "openai" },
+  { sum: "cost", count: true },
+);
+expect(rows).toEqual([{ sum_cost: 4, count: 2 }]);
+```
+
+See [entities.md](./entities.md#aggregates-sum--group-by--distinct) for result shape and guards.
+
 ### `simulateFlow`
 
 Simulate flow execution and inspect step history:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plumbus/core",
-  "version": "0.6.7",
+  "version": "0.6.8",
   "description": "Plumbus framework core — types, SDK, runtime, CLI, test utilities",
   "type": "module",
   "main": "./dist/index.js",
@@ -95,9 +95,9 @@
     "@vitest/browser": "^3.0.0",
     "esbuild": "^0.25.12",
     "typescript": "^5.7.0",
-    "@plumbus/api": "0.1.2",
+    "@plumbus/voice": "0.3.0",
     "@plumbus/mcp": "0.5.1",
-    "@plumbus/voice": "0.3.0"
+    "@plumbus/api": "0.1.2"
   },
   "scripts": {
     "build": "tsc -b",