@cosmicdrift/kumiko-framework 0.364.0 → 0.365.1

package/AGENTS.md

@@ -49,7 +49,10 @@ write the table yourself.
 **Handler.** The only way in. A write handler changes state, a query handler
 reads it. Both have a qualified name (QN), a Zod payload schema and an access
 rule. `r.crud(name, entity, options)` registers the entity plus create,
-update, delete, restore, list and detail handlers in one call. Turn single
+update, delete, restore, list and detail handlers in one call. Its options
+need an access rule for both sides, `write: { access }` and
+`read: { access }`; `verbAccess: { delete: { roles: ["Admin"] } }`
+overrides a single verb. Without them boot stops. Turn single
 verbs off with `verbs: { delete: false }` and register them yourself when
 they need different access or logic. Custom logic goes into
 `r.writeHandler(qn, schema, fn, { access })` and
@@ -60,7 +63,10 @@ executor from `createEntityExecutor(name, entity)`.
 `entityList`, `entityEdit`, `projectionList`, `projectionDetail`,
 `actionForm`, `dashboard` and `custom`. The renderer builds the UI from the
 declaration. Columns, sections, row actions, tabs, wizard steps and
-conditional fields are data, not JSX.
+conditional fields are data, not JSX. A `dashboard` lists `panels`; a
+`stat` panel names a query handler and the `valueField` to show from its
+result, and a `stat-group` panel holds several stats. The query returns one
+flat object with those fields.
 
 **Nav.** A sidebar entry: `r.nav({ id, label, screen, parent, order })`.
 Parents may belong to another feature; refer to them by QN.
@@ -83,6 +89,12 @@ that holds global data calls `r.systemScope()`.
 Screens and nav entries can narrow visibility further with their own
 `access`. Anonymous endpoints use the `anonymous` role. Field level and row
 level rules exist as well (see the table below).
+An `openToAll` write handler whose payload contains personal fields must
+say that every tenant member may write them:
+`{ openToAll: { reason: "...", personalData: "tenant-members" } }`. The
+alternatives are roles, or binding each row to its caller. Boot names all
+three. On query handlers `personalData` is only valid as
+`access: { roles: ["anonymous"], personalData: "public-intake" }`.
 
 **Personal data.** Every text field says whether it holds personal data;
 the field types reject a text field without that stance.
@@ -90,7 +102,10 @@ the field types reject a text field without that stance.
 business data. For personal data name the subject, `personal: "self"`,
 `personal: { of: "<ownerField>" }` or `personal: "tenant"`, plus
 `find: "exact" | "fuzzy" | "none" | "secret"`. A plain foreign key to a user
-is `personal: "ref"`. The framework encrypts personal fields per subject and
+is `personal: "ref"`. `personal: "self"` is for the row that is the user.
+When the record itself is the person, such as a contact or a customer that
+is not a user, use `personal: { of: "id" }`; the entity then needs a uuid
+`id`. The framework encrypts personal fields per subject and
 can erase them on request.
 
 **Client.** The web side of a feature is a `ClientFeatureDefinition` in the
@@ -145,9 +160,15 @@ feature and test. Start from them.
 | Unit tests | `bun run test` |
 | Integration tests (needs `docker compose up -d`) | `bun run test:integration` |
 | Browser tests | `bun run e2e` |
-| New migration after an entity change | `bun run schema:generate` |
+| New migration after an entity change or a newly mounted bundled feature | `bun run schema:generate <name>` |
+| Check migrations against the features, no database needed | `bun kumiko-schema validate` |
 | Apply migrations | `bun run schema:apply` |
 
+`<name>` is required and becomes part of the file name
+(`schema:generate add-invoice`). Mounting a bundled feature in
+`APP_FEATURES` adds its tables, so it needs a migration like your own
+entities do.
+
 ## Rules: never this, do that
 
 These rules are enforced by boot validation, guards or review. Breaking them
@@ -164,6 +185,11 @@ produces code that compiles and then fails in production.
 - Never hand-write SQL for reads that an executor `list` or `detail` covers.
   Use `r.queryHandler` with the executor, or a projection with
   `ctx.queryProjection`.
+- Never filter or count the rows of one `list` page in code. `list` returns
+  one page (default 50, `limit` at most 200). Pass
+  `filter: { field, op, value }` (`eq`, `ne`, `lt`, `gt`, `lte`, `gte`, `in`)
+  so the database filters, and `totalCount: true` to get `total` over all
+  matching rows; `limit: 1, totalCount: true` is a count query.
 - Never change an event schema in place once it has been emitted. Version it
   (see `agents/examples/event-sourcing.md`).
 - Never read or write another tenant's data. `ctx.db` is tenant scoped on
@@ -237,6 +263,8 @@ as bundled features.
 | --- | --- | --- |
 | A CRUD entity with list and edit | `createEntity` + `r.crud` + `entityList` / `entityEdit` screens | `agents/examples/basic-entity.md` |
 | Business logic beyond CRUD | `r.writeHandler` / `r.queryHandler` with `createEntityExecutor` | `agents/examples/custom-handlers.md` |
+| Filtered lists and counts | Executor `list` with `filter` and `totalCount` | `agents/examples/custom-handlers.md` |
+| Key figures on a dashboard | `dashboard` screen with `stat` / `stat-group` panels and a query handler | `agents/examples/dashboard-stats.md` |
 | Relations between entities | `r.relation(entity, name, { type, target, foreignKey, onDelete })` | `agents/examples/relations.md` |
 | Structured sub-objects in a field | Embedded fields | `agents/examples/embedded.md` |
 | List, edit, custom screens and navs | `r.screen`, `r.nav` | `agents/examples/screens-nav.md` |
@@ -283,7 +311,10 @@ source file with its path. `src/feature.ts` holds the feature;
 the framework repo set up their stack with `setupTestStack` from
 `@cosmicdrift/kumiko-framework/stack` and create tables in the test. In an
 app, `setupAppTestStack` and `seedTenant` do that for you; keep the
-assertions, take the setup from your scaffolded integration test.
+assertions, take the setup from your scaffolded integration test. Table
+setup in sample tests (`unsafeCreateEntityTable`, `createEventsTable`) and
+any raw `DELETE FROM` cleanup are framework internals. Never copy them;
+isolate tests with one tenant each.
 
 Some samples import from `@app/define`. That alias points at the generated
 `.kumiko/define.ts`, which re-exports the engine with event types narrowed to

package/agents/examples/anonymous-access-multitenant.md

@@ -39,7 +39,6 @@ bun test
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { setTenantCookie } from "@cosmicdrift/kumiko-framework/api";
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
@@ -48,7 +47,7 @@ import {
   TestUsers,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
-import { multiTenantShopFeature, productEntity, productTable } from "../feature";
+import { multiTenantShopFeature, productEntity } from "../feature";
 import { createSubdomainResolver, extractSubdomain } from "../subdomain-resolver";
 
 const ACME_TENANT_ID = "00000000-0000-4000-8000-000000000001" as TenantId;
@@ -61,6 +60,9 @@ const KNOWN_TENANTS: Record<string, TenantId> = {
   globex: GLOBEX_TENANT_ID,
 };
 
+// Unique value: the acme tenant is fixed, so the row is told apart by name, not by reset.
+const ACME_PRODUCT_NAME = "Acme Anvil (subdomain read)";
+
 let stack: TestStack;
 let resolver: ReturnType<typeof createSubdomainResolver>;
 // Counters prove that the cache actually hits — one DB lookup per
@@ -110,8 +112,7 @@ afterAll(async () => {
   await stack?.cleanup();
 });
 
-beforeEach(async () => {
-  await asRawClient(stack.db).unsafe(`DELETE FROM "${productTable.tableName}"`);
+beforeEach(() => {
   resolver.invalidateAll();
   lookupCount = 0;
   existsCount = 0;
@@ -123,7 +124,7 @@ describe("subdomain resolution", () => {
     // visitors who land on acme.shop.com.
     await stack.http.writeOk(
       "mtshop:write:product:create",
-      { name: "Acme Anvil" },
+      { name: ACME_PRODUCT_NAME },
       { ...TestUsers.admin, tenantId: ACME_TENANT_ID },
     );
 
@@ -136,7 +137,9 @@ describe("subdomain resolution", () => {
 
     expect(res.status).toBe(200);
     const body = (await res.json()) as { data: Array<{ name: string }> };
-    expect(body.data.map((p) => p.name)).toEqual(["Acme Anvil"]);
+    expect(body.data.map((p) => p.name).filter((name) => name === ACME_PRODUCT_NAME)).toEqual([
+      ACME_PRODUCT_NAME,
+    ]);
   });
 
   test("unknown subdomain → 400 tenant_required (resolver returned null)", async () => {

package/agents/examples/anonymous-access.md

@@ -41,8 +41,8 @@ bun test
 // that parses the host (acme.shop.com → tenantId) plus a tenantExists
 // callback that confirms the tenant is real (against DB or cache).
 
-import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { ANONYMOUS_USER_ID, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
@@ -56,11 +56,14 @@ import {
   guestOrderEntity,
   guestOrderTable,
   productEntity,
-  productTable,
 } from "../feature";
 
 const TENANT_ID = "00000000-0000-4000-8000-000000000001" as TenantId;
 
+// Unique per test: the tenant is fixed, so rows are told apart by value, not by reset.
+const PRODUCT_NAME = "Espresso Beans (anonymous read)";
+const GUEST_EMAIL = "guest-checkout@example.com";
+
 let stack: TestStack;
 
 beforeAll(async () => {
@@ -79,16 +82,11 @@ afterAll(async () => {
   await stack?.cleanup();
 });
 
-beforeEach(async () => {
-  await asRawClient(stack.db).unsafe(`DELETE FROM "${productTable.tableName}"`);
-  await asRawClient(stack.db).unsafe(`DELETE FROM "${guestOrderTable.tableName}"`);
-});
-
 describe("public read: anonymous + authenticated share the listing", () => {
   test("anonymous caller sees products without any auth headers", async () => {
     await stack.http.writeOk(
       "shop:write:product:create",
-      { name: "Espresso Beans", priceCents: "1500" },
+      { name: PRODUCT_NAME, priceCents: "1500" },
       TestUsers.admin,
     );
 
@@ -99,17 +97,11 @@ describe("public read: anonymous + authenticated share the listing", () => {
 
     expect(res.status).toBe(200);
     const body = (await res.json()) as { data: Array<{ name: string }> };
-    expect(body.data).toHaveLength(1);
-    expect(body.data[0]?.name).toBe("Espresso Beans");
+    const mine = body.data.filter((product) => product.name === PRODUCT_NAME);
+    expect(mine).toHaveLength(1);
   });
 
   test("authenticated user reaches the same handler via JWT", async () => {
-    await stack.http.writeOk(
-      "shop:write:product:create",
-      { name: "Espresso Beans", priceCents: "1500" },
-      TestUsers.admin,
-    );
-
     const res = await stack.http.query("shop:query:product:list", {}, TestUsers.user);
     expect(res.status).toBe(200);
   });
@@ -117,26 +109,22 @@ describe("public read: anonymous + authenticated share the listing", () => {
 
 describe("guest checkout: anonymous write lands with placedBy=anonymous", () => {
   test("anonymous order is stored and tagged with the anonymous user-id", async () => {
-    await stack.http.writeOk(
-      "shop:write:product:create",
-      { name: "Espresso Beans", priceCents: "1500" },
-      TestUsers.admin,
-    );
-
     const res = await stack.http.raw("POST", "/api/write", {
       type: "shop:write:guest-order:place",
       payload: {
         productId: "00000000-0000-4000-8000-000000000099",
-        email: "guest@example.com",
+        email: GUEST_EMAIL,
       },
     });
 
     expect(res.status).toBe(200);
 
-    const orders = await selectMany(stack.db, guestOrderTable);
+    const orders = (await selectMany(stack.db, guestOrderTable)).filter(
+      (order) => order.email === GUEST_EMAIL,
+    );
     expect(orders).toHaveLength(1);
     expect(orders[0]?.placedBy).toBe(ANONYMOUS_USER_ID);
-    expect(orders[0]?.email).toBe("guest@example.com");
+    expect(orders[0]?.email).toBe(GUEST_EMAIL);
   });
 });
 

package/agents/examples/auth-mfa.md

@@ -18,7 +18,7 @@ The production wiring shape: mount `createAuthMfaFeature()` next to `createAuthE
 
 1. `createAuthMfaFeature({ setupTokenSecret, challengeTokenSecret, issuer })` builds the feature; `mfaStatusCheckerFromFeature(mfaFeature)` reads its login-status callback back off.
 2. That callback goes into `createAuthEmailPasswordFeature({ mfaStatusChecker: ... })` — `login.write.ts` calls it after the password check to decide whether to mint a JWT or a challenge.
-3. `buildServer({ auth: { mfaVerifyHandler: AuthMfaHandlers.verify } })` mounts `POST /auth/mfa/verify`, a framework route (not a dispatcher write-handler) with its own rate limiter, since it runs before a JWT exists.
+3. `buildServer({ auth: { mfaVerifyHandler: AuthMfaHandlers.verify, switchTenantMfaGateHandler: AuthHandlers.switchTenantMfaGate } })` (the gate is required with `mfaVerifyHandler`, so a tenant switch asks for the second factor too) mounts `POST /auth/mfa/verify`, a framework route (not a dispatcher write-handler) with its own rate limiter, since it runs before a JWT exists.
 4. If `sessions` is mounted too, `bindMfaRevokeAllOtherSessionsFromFeature(mfaFeature)?.(sessionCallbacks.sessionRevokeAllOthers)` wires "enable/disable/regenerate signs out every other session."
 
 ## What to copy into your app
@@ -51,6 +51,7 @@ const server = buildServer({
     membershipQuery: "tenant:query:memberships",
     loginHandler: "auth-email-password:[REDACTED:API key param]",
     mfaVerifyHandler: AuthMfaHandlers.verify,
+    switchTenantMfaGateHandler: AuthHandlers.switchTenantMfaGate,
     sessionCreator: sessionCallbacks.sessionCreator,
     sessionRevoker: sessionCallbacks.sessionRevoker,
     sessionChecker: sessionCallbacks.sessionChecker,
@@ -86,7 +87,7 @@ Apps built via `runDevApp`/`runProdApp` (the dev-server bootstrap used by `creat
 // the resulting app behaves like this test asserts: login is two-step once
 // MFA is enabled, and a valid TOTP code completes it.
 
-import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import {
   AuthHandlers,
   createAuthEmailPasswordFeature,
@@ -106,9 +107,7 @@ import {
   createUserFeature,
   UserHandlers,
   userEntity,
-  userTable,
 } from "@cosmicdrift/kumiko-bundled-features/user";
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 import { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
@@ -158,6 +157,7 @@ beforeAll(async () => {
       membershipQuery: "tenant:query:memberships",
       loginHandler: AuthHandlers.login,
       mfaVerifyHandler: AuthMfaHandlers.verify,
+      switchTenantMfaGateHandler: AuthHandlers.switchTenantMfaGate,
     },
   });
 
@@ -172,11 +172,6 @@ afterAll(async () => {
   configureEntityFieldEncryption(undefined);
 });
 
-beforeEach(async () => {
-  await asRawClient(stack.db).unsafe(`DELETE FROM "${userTable.tableName}"`);
-  await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
-});
-
 describe("auth-mfa sample wiring", () => {
   test("login without MFA enrolled returns a JWT directly", async () => {
     const hash = await hashPassword("super-long-password");
@@ -287,6 +282,7 @@ describe("auth-mfa sample wiring", () => {
 //       membershipQuery: "tenant:query:memberships",
 //       loginHandler: "auth-email-password:[REDACTED:API key param]",
 //       mfaVerifyHandler: AuthMfaHandlers.verify,
+//       switchTenantMfaGateHandler: AuthHandlers.switchTenantMfaGate,
 //       sessionCreator: sessionCallbacks.sessionCreator,
 //       sessionRevoker: sessionCallbacks.sessionRevoker,
 //       sessionChecker: sessionCallbacks.sessionChecker,

package/agents/examples/custom-fields-basic.md

@@ -113,17 +113,19 @@ import {
   createCustomFieldsFeature,
   fieldDefinitionEntity,
 } from "@cosmicdrift/kumiko-bundled-features/custom-fields";
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
   createTestUser,
   setupTestStack,
   type TestStack,
+  testTenantId,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { propertyEntity, propertyFeature } from "../feature";
 
-const admin = createTestUser({ roles: ["TenantAdmin"] });
+// Each test runs in its own tenant, so rows from other tests never show up.
+let admin = createTestUser({ roles: ["TenantAdmin"], tenantId: testTenantId(1) });
+let nextTenant = 1;
 const customFields = createCustomFieldsFeature();
 
 let stack: TestStack;
@@ -139,10 +141,9 @@ afterAll(async () => {
   await stack.cleanup();
 });
 
-beforeEach(async () => {
-  await asRawClient(stack.db).unsafe(`DELETE FROM kumiko_events`);
-  await asRawClient(stack.db).unsafe(`DELETE FROM read_sample_cf_properties`);
-  await asRawClient(stack.db).unsafe(`DELETE FROM read_custom_field_definitions`);
+beforeEach(() => {
+  nextTenant += 1;
+  admin = createTestUser({ roles: ["TenantAdmin"], tenantId: testTenantId(nextTenant) });
 });
 
 async function defineField(fieldKey: string, type = "text") {

package/agents/examples/custom-handlers.md

@@ -30,9 +30,10 @@ logic is yours.
 - **`skipOptimisticLock` for last-writer-wins** — `reset` deliberately
   bypasses the version check because the operation is admin-driven and
   resetting twice is semantically the same as resetting once.
-- **Custom queries** — `counter:active` filters the projection in
-  TypeScript after the executor's list returns. Useful when the filter is
-  computed (above-threshold) rather than indexed.
+- **Custom queries** — `counter:active` passes a server-side `filter`
+  (`eq`/`ne`/`lt`/`gt`/`lte`/`gte`/`in`) and `totalCount` to the executor's
+  list. Never filter a page in TypeScript: list is paginated, so rows after
+  the first page would be missed.
 - **`failNotFound` helper** — typed error response for the 404 case
   without a hand-built `KumikoError` subclass.
 
@@ -69,6 +70,7 @@ import {
   setupTestStack,
   type TestStack,
   TestUsers,
+  testTenantId,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { expectErrorIncludes } from "@cosmicdrift/kumiko-framework/testing";
@@ -231,44 +233,80 @@ describe("custom write handler: reset", () => {
 });
 
 describe("custom query handler: active counters", () => {
+  // Own tenants: the total assertions would otherwise count counters created by other tests.
+  const activeAdmin = createTestUser({ roles: ["Admin"], tenantId: testTenantId(11) });
+  const activeUser = createTestUser({ id: 2, roles: ["User"], tenantId: testTenantId(11) });
+  const otherAdmin = createTestUser({ roles: ["Admin"], tenantId: testTenantId(12) });
+
   test("filters counters by minimum count", async () => {
     const c1 = await stack.http.writeOk<SaveContext>(
       "counters:write:counter:create",
       { name: "active-a" },
-      admin,
+      activeAdmin,
     );
     const c2 = await stack.http.writeOk<SaveContext>(
       "counters:write:counter:create",
       { name: "active-b" },
-      admin,
+      activeAdmin,
     );
     await stack.http.writeOk<SaveContext>(
       "counters:write:counter:create",
       { name: "inactive" },
-      admin,
+      activeAdmin,
     );
 
     await stack.http.writeOk<SaveContext>(
       "counters:write:counter:increment",
       { id: c1.id, amount: 10 },
-      user,
+      activeUser,
     );
     await stack.http.writeOk<SaveContext>(
       "counters:write:counter:increment",
       { id: c2.id, amount: 5 },
-      user,
+      activeUser,
     );
 
-    const result = await stack.http.queryOk<{ rows: Record<string, unknown>[] }>(
-      "counters:query:counter:active",
-      { minCount: 5 },
-      admin,
-    );
+    const result = await stack.http.queryOk<{
+      rows: Record<string, unknown>[];
+      nextCursor: string | null;
+      total?: number;
+    }>("counters:query:counter:active", { minCount: 5 }, activeAdmin);
 
     const names = result.rows.map((r) => r["name"]);
     expect(names).toContain("active-a");
     expect(names).toContain("active-b");
     expect(names).not.toContain("inactive");
+    expect(result.total).toBe(2);
+  });
+
+  test("total and nextCursor describe the full filtered set", async () => {
+    for (const name of ["total-a", "total-b", "total-c"]) {
+      const created = await stack.http.writeOk<SaveContext>(
+        "counters:write:counter:create",
+        { name },
+        otherAdmin,
+      );
+      await stack.http.writeOk<SaveContext>(
+        "counters:write:counter:increment",
+        { id: created.id, amount: 1 },
+        otherAdmin,
+      );
+    }
+    await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:create",
+      { name: "total-untouched" },
+      otherAdmin,
+    );
+
+    const result = await stack.http.queryOk<{
+      rows: Record<string, unknown>[];
+      nextCursor: string | null;
+      total?: number;
+    }>("counters:query:counter:active", { minCount: 1 }, otherAdmin);
+
+    expect(result.rows).toHaveLength(3);
+    expect(result.total).toBe(3);
+    expect(result.nextCursor).toBeNull();
   });
 });
 ```
@@ -277,7 +315,7 @@ describe("custom query handler: active counters", () => {
 
 ```ts
 // Custom Handlers Sample
-// Shows: writeHandler with business logic, queryHandler with custom filtering,
+// Shows: writeHandler with business logic, queryHandler with a server-side filter,
 // handler that modifies payload before DB write.
 
 import {
@@ -290,6 +328,9 @@ import {
 import { failNotFound } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 
+// detail() returns an untyped row; parse the two fields the increment needs once.
+const counterVersionRowSchema = z.object({ count: z.number(), version: z.number() });
+
 export const counterEntity = createEntity({
   table: "read_sample_counters",
   fields: {
@@ -326,13 +367,14 @@ export const counterFeature = defineFeature("counters", (r) => {
         return failNotFound("counter", event.payload.id);
       }
 
-      const newCount = (current["count"] as number) + event.payload.amount;
+      const { count, version } = counterVersionRowSchema.parse(current);
+      const newCount = count + event.payload.amount;
       // Read-modify-write on counter: use the version we just read so two
       // concurrent increments don't clobber each other's changes.
       return counterExecutor.update(
         {
           id: event.payload.id,
-          version: current["version"] as number,
+          version,
           changes: { count: newCount, lastIncrementedBy: `user:${event.user.id}` },
         },
         event.user,
@@ -358,17 +400,22 @@ export const counterFeature = defineFeature("counters", (r) => {
     { access: { roles: ["Admin"] } },
   );
 
-  // Custom query: only counters above a threshold
+  // Custom query: only counters above a threshold. list() returns one page
+  // (default 50, max 200, MAX_LIST_LIMIT), so a JS filter would miss rows after
+  // page 1; filter in the query instead. totalCount counts over the whole WHERE.
   r.queryHandler(
     "counter:active",
-    z.object({ minCount: z.number().default(1) }),
-    async (query, ctx) => {
-      const all = await counterExecutor.list({}, query.user, ctx.db);
-      return {
-        ...all,
-        rows: all.rows.filter((r) => (r["count"] as number) >= query.payload.minCount),
-      };
-    },
+    z.object({ minCount: z.number().int().default(1), cursor: z.string().optional() }),
+    async (query, ctx) =>
+      counterExecutor.list(
+        {
+          filter: { field: "count", op: "gte", value: query.payload.minCount },
+          totalCount: true,
+          cursor: query.payload.cursor,
+        },
+        query.user,
+        ctx.db,
+      ),
     {
       access: {
         openToAll: {