@zeroxsolutions/db 9.5.0 → 10.0.0

package/CHANGELOG.md

@@ -1,3 +1,27 @@
+# 10.0.0 (2026-10-18)
+
+### 🚀 Features
+
+- ⚠️ **db:** split the base repository as spring data does over a neutral read ([2b6fdba](https://github.com/zeroxsolutions/zeroxsolutions/commit/2b6fdba))
+
+### ⚠️ Breaking Changes
+
+- **db:** split the base repository as spring data does over a neutral read ([2b6fdba](https://github.com/zeroxsolutions/zeroxsolutions/commit/2b6fdba))
+  `findOne`, `findAll(where)`, `findAllAndCount(where)`,
+  `count(where)`, `exists`, `update`, `delete`, `softDelete` and `nullifyBy`
+  are no longer public; reads take `read`, `filter`, `orderBy`, `limit` and
+  `offset` in place of `fields`, `include`, `with`, `sort` and `filter`, have no
+  `tx` and no default page window; `TableQuery`, `assertQueryableFields`,
+  `buildFilterConditions`, `buildOrderBy`, the filter resolvers,
+  `relationshipsOf` (now `relationsOf`) and the page-size constants are gone;
+  `BaseRepository` takes `READS` as its fourth argument and
+  `BaseViewRepository` its key columns as its third.
+
+### ❤️ Thank You
+
+- Claude Opus 5.5
+- Lương Văn Tú
+
 ## 9.5.0 (2026-10-16)
 
 ### 🚀 Features
@@ -107,11 +131,11 @@ This was a version bump only for @zeroxsolutions/db to align it with other proje
 
 ### 🩹 Fixes
 
-- ⚠️  **db:** take zod and drizzle-orm from the host, not a second copy ([128a772](https://github.com/zeroxsolutions/zeroxsolutions/commit/128a772))
+- ⚠️ **db:** take zod and drizzle-orm from the host, not a second copy ([128a772](https://github.com/zeroxsolutions/zeroxsolutions/commit/128a772))
 
-### ⚠️  Breaking Changes
+### ⚠️ Breaking Changes
 
-- **db:** take zod and drizzle-orm from the host, not a second copy  ([128a772](https://github.com/zeroxsolutions/zeroxsolutions/commit/128a772))
+- **db:** take zod and drizzle-orm from the host, not a second copy ([128a772](https://github.com/zeroxsolutions/zeroxsolutions/commit/128a772))
   `zod` and `drizzle-orm` are peer dependencies now. A consumer
   already installing both is unaffected; one that relied on db to drag them in
   must declare them itself.
@@ -129,11 +153,11 @@ This was a version bump only for @zeroxsolutions/db to align it with other proje
 
 ### 🚀 Features
 
-- ⚠️  **db:** load a read's fieldsets and include paths off the schema ([90cbd8c](https://github.com/zeroxsolutions/zeroxsolutions/commit/90cbd8c))
+- ⚠️ **db:** load a read's fieldsets and include paths off the schema ([90cbd8c](https://github.com/zeroxsolutions/zeroxsolutions/commit/90cbd8c))
 
-### ⚠️  Breaking Changes
+### ⚠️ Breaking Changes
 
-- **db:** load a read's fieldsets and include paths off the schema  ([90cbd8c](https://github.com/zeroxsolutions/zeroxsolutions/commit/90cbd8c))
+- **db:** load a read's fieldsets and include paths off the schema ([90cbd8c](https://github.com/zeroxsolutions/zeroxsolutions/commit/90cbd8c))
   `include` and `fields` are typed by `TableQuery`, so an
   unguarded `string[]` no longer compiles where the schema generics are given;
   `buildRelationalWith` is replaced by `buildRelationalRead`; the view
@@ -153,14 +177,14 @@ This was a version bump only for @zeroxsolutions/db to align it with other proje
 
 ### 🩹 Fixes
 
-- ⚠️  **db:** the audit columns store an instant, not a wall clock ([8760d45](https://github.com/zeroxsolutions/zeroxsolutions/commit/8760d45))
+- ⚠️ **db:** the audit columns store an instant, not a wall clock ([8760d45](https://github.com/zeroxsolutions/zeroxsolutions/commit/8760d45))
 
-### ⚠️  Breaking Changes
+### ⚠️ Breaking Changes
 
-- **db:** the audit columns store an instant, not a wall clock  ([8760d45](https://github.com/zeroxsolutions/zeroxsolutions/commit/8760d45))
+- **db:** the audit columns store an instant, not a wall clock ([8760d45](https://github.com/zeroxsolutions/zeroxsolutions/commit/8760d45))
   every Postgres consumer must run `drizzle:generate` and apply the
   migration it emits. Read that SQL before committing it: a bare `ALTER COLUMN ... SET DATA
-  TYPE timestamptz` reinterprets existing values in the session's time zone, so a store
+TYPE timestamptz` reinterprets existing values in the session's time zone, so a store
   holding rows needs `USING <column> AT TIME ZONE 'UTC'` written explicitly rather than the
   server default. A consumer that bumps without migrating keeps its old columns and gets the
   new type only on tables it creates afterwards, which is the state this is worth a major to
@@ -184,11 +208,11 @@ This was a version bump only for @zeroxsolutions/db to align it with other proje
 
 ### 💅 Refactors
 
-- ⚠️  **query,response,server:** one wire spelling, flat exports ([5c57b3a](https://github.com/zeroxsolutions/zeroxsolutions/commit/5c57b3a))
+- ⚠️ **query,response,server:** one wire spelling, flat exports ([5c57b3a](https://github.com/zeroxsolutions/zeroxsolutions/commit/5c57b3a))
 
-### ⚠️  Breaking Changes
+### ⚠️ Breaking Changes
 
-- **query,response,server:** one wire spelling, flat exports  ([5c57b3a](https://github.com/zeroxsolutions/zeroxsolutions/commit/5c57b3a))
+- **query,response,server:** one wire spelling, flat exports ([5c57b3a](https://github.com/zeroxsolutions/zeroxsolutions/commit/5c57b3a))
   `@zeroxsolutions/response/http`, `@zeroxsolutions/query/http`
   and `@zeroxsolutions/server/hono/http` are gone, and the surviving `/jsonapi`
   and `/hono` subpaths move to the package root. Every import drops its subpath.
@@ -223,11 +247,11 @@ This was a version bump only for @zeroxsolutions/db to align it with other proje
 
 ### 🚀 Features
 
-- ⚠️  **db:** let each table declare its own id column ([eca4aca](https://github.com/zeroxsolutions/zeroxsolutions/commit/eca4aca))
+- ⚠️ **db:** let each table declare its own id column ([eca4aca](https://github.com/zeroxsolutions/zeroxsolutions/commit/eca4aca))
 
-### ⚠️  Breaking Changes
+### ⚠️ Breaking Changes
 
-- **db:** let each table declare its own id column  ([eca4aca](https://github.com/zeroxsolutions/zeroxsolutions/commit/eca4aca))
+- **db:** let each table declare its own id column ([eca4aca](https://github.com/zeroxsolutions/zeroxsolutions/commit/eca4aca))
   `baseTable` is removed - take `idColumn` and spread
   `timestamps`. `defaultIndexedBaseColumns` is now `timestampIndexes` and
   `BaseTableShape` is `TimestampColumns`; both were named for the removed concept.
@@ -373,11 +397,11 @@ This was a version bump only for @zeroxsolutions/db to align it with other proje
 
 ### 🚀 Features
 
-- ⚠️  **db:** speak the wire's query vocabulary, and only it ([12801f0](https://github.com/zeroxsolutions/zeroxsolutions/commit/12801f0))
+- ⚠️ **db:** speak the wire's query vocabulary, and only it ([12801f0](https://github.com/zeroxsolutions/zeroxsolutions/commit/12801f0))
 
-### ⚠️  Breaking Changes
+### ⚠️ Breaking Changes
 
-- **db:** speak the wire's query vocabulary, and only it  ([12801f0](https://github.com/zeroxsolutions/zeroxsolutions/commit/12801f0))
+- **db:** speak the wire's query vocabulary, and only it ([12801f0](https://github.com/zeroxsolutions/zeroxsolutions/commit/12801f0))
   `FindAllOptions.orderBy` is now `sort` and `FilterQuery.filters`
   is now `filter`, in both the Postgres and D1 dialects. `baseQuerySchema`,
   `BaseQuery`, `OrderByValue` and `orderByValueSchema` are removed; a sort clause
@@ -439,11 +463,11 @@ This was a version bump only for @zeroxsolutions/db to align it with other proje
 ### 🚀 Features
 
 - **db:** hold FilterNode to the wire package's FilterTree at typecheck ([fb2a9a6](https://github.com/zeroxsolutions/zeroxsolutions/commit/fb2a9a6))
-- ⚠️  **db:** carry filters as a tree and refuse an inapplicable one ([1706c52](https://github.com/zeroxsolutions/zeroxsolutions/commit/1706c52))
+- ⚠️ **db:** carry filters as a tree and refuse an inapplicable one ([1706c52](https://github.com/zeroxsolutions/zeroxsolutions/commit/1706c52))
 
-### ⚠️  Breaking Changes
+### ⚠️ Breaking Changes
 
-- **db:** carry filters as a tree and refuse an inapplicable one  ([1706c52](https://github.com/zeroxsolutions/zeroxsolutions/commit/1706c52))
+- **db:** carry filters as a tree and refuse an inapplicable one ([1706c52](https://github.com/zeroxsolutions/zeroxsolutions/commit/1706c52))
   `buildFilterConditions` takes one options object;
   `filters` is a `FilterNode[]` tree; `baseQuerySchema` validates decoded
   objects and has no `search`; `serializeQuery` is removed - rendering the
@@ -626,4 +650,4 @@ This was a version bump only for @zeroxsolutions/db to align it with other proje
 
 ### ❤️ Thank You
 
-- Lương Văn Tú
+- Lương Văn Tú

package/README.md

@@ -5,16 +5,17 @@ A shared database library providing base entities, repository patterns, and quer
 ## Features
 
 - Base table schema with common audit columns (`id`, `createdAt`, `updatedAt`, `deletedAt`)
-- Abstract `BaseRepository` with full CRUD, soft-delete, pagination, and relation support
-- `BaseViewRepository` for PostgreSQL materialized views
-- Type-safe filter and ordering utilities with Zod validation, plus a `QueryableFields` whitelist guard
-  (`assertQueryableFields`) keyed to the row type, so a removed column fails typecheck at the whitelist
+- Abstract `BaseRepository` split as a Spring Data repository is: public methods that take no condition, and
+  protected ones taking a `where` that only a finder the repository names can call
+- `BaseViewRepository` for PostgreSQL materialized views, reading with the options a table repository takes
+- Reads that name what they load: a `read` of columns and nested relations, a `filter` tree, an `orderBy` with the
+  primary key appended, and a page window only when one is given
+- `READS` (`defineReads`), declared once per context: each table's order as a relation and its `virtual` filter and
+  order names; `relationsOf` for the relationships a permit list names
 - The filter vocabulary the wire toolkit is generic over: `filterOperatorSchema` / `FilterOperator` (15 operators),
-  `filterValueSchema`, and typed refusals (`UnknownQueryField`, `InvalidQueryFilter`, `InvalidQuerySort`)
-- Finders read a JSON:API query as drizzle's relational config: `fields` and `include`, typed off the schema by
-  `TableQuery`, resolved by `buildRelationalRead`
+  `filterValueSchema`, and typed refusals (`UnknownQueryField`, `UnknownReadName`)
 - Transaction support for all operations
-- Automatic soft-delete filtering (excludes `deletedAt IS NOT NULL` by default)
+- Automatic soft-delete filtering at every level of a read (excludes `deletedAt IS NOT NULL` by default)
 - `DrizzleUnitOfWork` + transactional `outboxTable` / `DrizzleOutbox` - the `@zeroxsolutions/cosmic` `IUnitOfWork` port implementation (atomic use case + domain events staged in the same transaction)
 
 ## Installation
@@ -33,13 +34,13 @@ Import from the subpath that matches your driver. **There is no root entry**: `p
 declares `"."`, but no `src/index.ts` exists for the build to emit it from, so
 `from '@zeroxsolutions/db'` does not resolve.
 
-| Export path                     | Description                                                                                                                                                                   |
-| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@zeroxsolutions/db/postgres`   | PostgreSQL entity, repository, view repository, unit of work, outbox, and types                                                                                               |
-| `@zeroxsolutions/db/d1`         | Cloudflare D1 (SQLite) entity, repository, unit of work, outbox, and types                                                                                                    |
-| `@zeroxsolutions/db/utils`      | Filter and order builders, `TableQuery` and the relational-read builder, the field-whitelist guard, the filter-value schema + operator enum, omit masks, pagination constants |
-| `@zeroxsolutions/db/testing`    | A throwaway Postgres container carrying your schema, on the engine you name, plus the container timeout and a fake uuid v7                                                    |
-| `@zeroxsolutions/db/containers` | The forced remove that tears down a container you started yourself                                                                                                            |
+| Export path                     | Description                                                                                                                |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `@zeroxsolutions/db/postgres`   | PostgreSQL entity, repository, view repository, unit of work, outbox, and types                                            |
+| `@zeroxsolutions/db/d1`         | Cloudflare D1 (SQLite) entity, repository, unit of work, outbox, and types                                                 |
+| `@zeroxsolutions/db/utils`      | `defineReads`, `relationsOf`, the read and order types, the filter-value schema + operator enum, the refusals, omit masks  |
+| `@zeroxsolutions/db/testing`    | A throwaway Postgres container carrying your schema, on the engine you name, plus the container timeout and a fake uuid v7 |
+| `@zeroxsolutions/db/containers` | The forced remove that tears down a container you started yourself                                                         |
 
 ---
 
@@ -77,94 +78,132 @@ export const users = pgTable(
 
 ### BaseRepository
 
-Extend `BaseRepository` to get a fully featured data access layer:
+Extend `BaseRepository`; a read or a write keyed by anything but the id is a finder you name, over a protected method:
 
 ```ts
 import { eq } from 'drizzle-orm';
-import { BaseRepository } from '@zeroxsolutions/db/postgres';
+import { BaseRepository, type FindAllOptions } from '@zeroxsolutions/db/postgres';
 import type { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
-import { users } from './schema';
-import type * as schema from './schema';
+import * as schema from './schema';
+import { READS, usersTable } from './schema';
 
-export class UserRepository extends BaseRepository<typeof users, typeof schema, 'users'> {
+export class UserRepository extends BaseRepository<typeof usersTable, typeof schema, 'usersTable'> {
   constructor(db: PostgresJsDatabase<typeof schema>) {
-    super(db, users, 'users'); // 'users' is the queryKey for relational queries
+    super(db, usersTable, 'usersTable', READS); // the export name, and the context's READS
   }
 
-  findOneByEmail(email: string) {
-    return this.findOne(eq(users.email, email));
+  findAllAndCountByTenantId(tenantId: string, options?: FindAllOptions<typeof schema, 'usersTable'>) {
+    return this.findAllAndCountWhere(eq(usersTable.tenantId, tenantId), options);
   }
 }
 ```
 
-#### Available Methods
-
-| Method                              | Description                                        |
-| ----------------------------------- | -------------------------------------------------- |
-| `findAll(where, options?)`          | Paginated list query                               |
-| `findAllAndCount(where, options?)`  | Paginated list + total count in parallel           |
-| `findOne(where, options?)`          | First matching record or `null`                    |
-| `findOneById(id, options?)`         | Find by primary key or `null`                      |
-| `create(data, options?)`            | Insert one record, returns inserted row            |
-| `createMany(data[], options?)`      | Bulk insert, returns inserted rows                 |
-| `update(where, data, options?)`     | Update matching records, returns first updated row |
-| `updateById(id, data, options?)`    | Update by primary key                              |
-| `delete(where, options?)`           | Hard delete matching records                       |
-| `deleteById(id, options?)`          | Hard delete by primary key                         |
-| `count(where, options?)`            | Count matching records                             |
-| `exists(where, options?)`           | Returns `true` if any record matches               |
-| `softDelete(where, options?)`       | Sets `deletedAt` to now                            |
-| `softDeleteById(id, options?)`      | Soft delete by primary key                         |
-| `nullifyBy(field, value, options?)` | Set field to `null` where field equals value       |
-
-#### FindAll Options
+The third argument is the table's EXPORT name in the schema, which drizzle's relational query looks a relation up
+by; omitted, a read that loads a relation throws.
+
+#### Public methods
+
+No public method takes a condition, so no SQL reaches the repository from outside it.
+
+| Method                             | Description                                                  |
+| ---------------------------------- | ------------------------------------------------------------ |
+| `findOneById(id, options?)`        | The row with that id, or `null`                              |
+| `findAllById(ids, options?)`       | Every row with one of those ids; no page window              |
+| `existsById(id, options?)`         | Whether a row holds the id                                   |
+| `findAll(options?)`                | The rows the options match                                   |
+| `findAllAndCount(options?)`        | Those rows, and the count under the same filter, in parallel |
+| `count(options?)`                  | How many rows the filter matches                             |
+| `create(data, options?)`           | Insert one row, returns it                                   |
+| `createMany(data[], options?)`     | Bulk insert, returns the rows                                |
+| `updateById(id, data, options?)`   | Update by id                                                 |
+| `deleteById(id, options?)`         | Hard delete by id                                            |
+| `deleteAllById(ids, options?)`     | Hard delete every id                                         |
+| `softDeleteById(id, options?)`     | Set `deletedAt` by id                                        |
+| `softDeleteAllById(ids, options?)` | Set `deletedAt` on every id                                  |
+
+On a multi-tenant table every one of them crosses tenants; a tenant-scoped repository exposes named finders instead.
+
+#### Protected methods
+
+`findOneWhere`, `findAllWhere`, `findAllAndCountWhere`, `countWhere`, `existsWhere`, `updateWhere`, `deleteWhere`,
+`softDeleteWhere` and `nullifyBy`, each taking a drizzle `where` beside the options. A finder's name states that
+condition (`findAllAndCountByTenantId`), the way a Spring Data derived query's does.
+
+#### Read options
 
 ```ts
-type FindAllOptions = {
-  tx?: Transaction;      // Run within a transaction
-  limit?: number;        // Default: 20; a larger value is clamped to 100, not rejected
-  offset?: number;       // Default: 0
-  softDeleted?: boolean; // Include soft-deleted records (default: false)
-  sort?: SortField[];    // [{ field: 'createdAt', direction: 'desc' }]; the primary key is appended
-  fields?: { books?: readonly ('title' | 'author')[] }; // Fieldsets keyed by TABLE name: columns and relations
-  include?: readonly ('author' | 'author.books')[];      // Relation paths, dot-separated (requires queryKey)
-  columns?: { authorId?: boolean }; // Root columns added to the root fieldset; never narrows the row
-  with?: { ... };        // Drizzle relational "with" clause, spelled out (requires queryKey)
+type FindOneOptions = {
+  read?: Read; // what loads; every column and no relation where absent
+  softDeleted?: boolean; // whether marked root rows match (default: false)
+  at?: Date; // the instant a virtual name is decided at (default: the call)
 };
+type FindAllOptions = FindOneOptions & {
+  filter?: FilterNode[]; // the condition tree; root nodes join by `and`
+  orderBy?: { field: string; direction: 'asc' | 'desc' }[]; // the primary key is appended
+  limit?: number; // with none, every match
+  offset?: number;
+};
+type CountOptions = { filter?: FilterNode[]; softDeleted?: boolean; at?: Date };
 ```
 
-`findAll` and `findAllAndCount` order by `sort` followed by each primary key column it does not
-already name, ascending, on both Postgres and D1. Rows that tie on `sort` have no order of their own,
-so without the key two pages could be cut from two orders of the same rows, repeating one row and
-skipping another. With no `sort`, a page is ordered by the key alone.
+A read holds no transaction: one that must see a write in progress belongs to an aggregate repository on the unit of
+work's executor. The writes still take `tx`.
+
+| `read` holds                   | The finder loads                                                            |
+| ------------------------------ | --------------------------------------------------------------------------- |
+| nothing                        | every column of the root table, and no relation                             |
+| `columns`                      | those columns; on the root table its primary key beside them                |
+| `relations.<name>`             | that relation under its own nested `read`, every column where it names none |
+| `relations.<name>.orderBy`     | the related rows in that order, in place of the one `READS` declares        |
+| `relations.<name>.softDeleted` | that relation's marked rows too                                             |
+
+The soft-delete condition holds at every level: a marked related row of a relation to one loads as `null`, and the
+marked rows of a relation to many are left out. A name the table does not hold throws `UnknownReadName`, naming its
+path. A read loading no relation takes a plain `select`, so a repository given no `queryKey` still narrows its row.
 
-`fields` and `include` are `TableQuery<typeof schema, '<export name>'>`, the shape `@zeroxsolutions/query` guards, so
-a guarded query spreads straight into the options:
+`findAll` and `findAllAndCount` order by `orderBy` followed by each primary key column it does not already name,
+ascending, on both Postgres and D1. Rows that tie have no order of their own, so without the key two pages could be cut
+from two orders of the same rows, repeating one row and skipping another.
 
-| The query says                | The finder loads                                                    |
-| ----------------------------- | ------------------------------------------------------------------- |
-| no fieldset for a table       | every column of that table                                          |
-| a fieldset                    | those columns and the table's primary key                           |
-| a relation name in a fieldset | that relation's primary keys - the linkage a relationship publishes |
-| an empty fieldset             | the primary key alone                                               |
-| an include path               | each relation on it, under its own table's fieldset                 |
+A filter or an order name resolves to a `virtual` name of the context's `READS` first, then to a relation to one row,
+compared by the related row's id (`equals` and `in` only), then to a column; anything else throws `UnknownQueryField`
+before any SQL is built.
 
-`with` and `include` reach the same relational query; where both name one relation, `with` wins. A read loading no
-relation takes a plain `select` of the columns it narrowed to, so a repository given no `queryKey` still narrows its
-own row. An include path is typed three relations deep; spell a deeper one out with `with`.
+#### READS
+
+```ts
+import { defineReads } from '@zeroxsolutions/db/utils';
+
+export const READS = defineReads(schema, {
+  openingHoursTable: { orderBy: [{ field: 'weekday', direction: 'asc' }] },
+  placesTable: {
+    virtual: {
+      'openState.status': {
+        filter: (condition, { at }) => sql`(<an expression over ${placesTable.id} and ${at}>) = ${condition.value}`,
+        order: ({ at }) => sql`<an expression over ${placesTable.id} and ${at}>`,
+      },
+    },
+  },
+});
+```
+
+Each key is a table's export name and each order field one of its columns, checked when `defineReads` runs. A
+`virtual` filter expression is wrapped in parentheses, so its `or` cannot reach the soft-delete condition.
 
 #### Nullify FK
 
-Set a foreign key column to `null` where it matches a given value. Useful when soft-deleting a parent but keeping child rows:
+`nullifyBy` sets a foreign key column to `null` where it matches a given value, from inside a named method:
 
 ```ts
 // Set categoryId = null on all transactions where categoryId = '123'
-await transactionRepo.nullifyBy('categoryId', '123', { tx });
+detachCategory(categoryId: string, tx: Transaction) {
+  return this.nullifyBy('categoryId', categoryId, { tx });
+}
 ```
 
 #### Transactions
 
-All methods accept an optional `tx` in their options:
+Every write accepts an optional `tx` in its options:
 
 ```ts
 await db.transaction(async (tx) => {
@@ -182,7 +221,7 @@ import { userSummaryView } from './views';
 // The same schema-typed client the service's table repositories take.
 export class UserSummaryViewRepository extends BaseViewRepository<typeof userSummaryView, typeof schema> {
   constructor(db: PostgresJsDatabase<typeof schema>) {
-    super(db, userSummaryView);
+    super(db, userSummaryView, ['tenantId']); // the columns of the view's unique index
   }
 }
 
@@ -190,10 +229,13 @@ export class UserSummaryViewRepository extends BaseViewRepository<typeof userSum
 await repo.refresh({ concurrently: true });
 ```
 
-`findAll` takes `FindAllViewOptions` - `tx`, `limit`, `offset` and `fields` - and `findOne` the same without the page
-window. `fields` is keyed by the view's name; a fieldset loads those columns and any the view selected from a table's
-primary key. A view has no `deletedAt` and no relational config, so it takes no `softDeleted`, `with` or `include`,
-and a view read is ordered in the view's own definition.
+A view repository reads with the options a table repository takes, without relations, `softDeleted` or `at`:
+`FindAllViewOptions` holds a `read` of `columns`, `filter`, `orderBy`, `limit` and `offset`, `FindOneViewOptions` the
+`read`, and `CountViewOptions` the `filter`. Its public `findAll`, `findAllAndCount` and `count` take no condition, and
+the protected `findAllWhere`, `findOneWhere`, `findAllAndCountWhere` and `countWhere` do. The constructor's third
+argument, the columns of the view's unique index, is appended to every order: a materialized view is read back with no
+order of its own, and PostgreSQL documents that different `LIMIT` and `OFFSET` values give inconsistent results
+without an `ORDER BY` that fixes one.
 
 ### Unit of Work & Transactional Outbox
 
@@ -330,27 +372,8 @@ sends it), with the same two indexes over the unsent rows as the Postgres table.
 
 ## Utilities
 
-Import from `@zeroxsolutions/db/utils`.
-
-### Filter Builder
-
-Converts typed filter descriptors into Drizzle `SQL` conditions:
-
-Takes one options object, so a parsed wire query spreads straight in. Returns `undefined` when the
-tree contributes no condition, and throws `UnknownQueryField` when a clause names a column the table
-does not hold:
-
-```ts
-import { buildFilterConditions } from '@zeroxsolutions/db/utils';
-
-const condition = buildFilterConditions({
-  table: users,
-  filter: [
-    { field: 'name', operator: 'contains', value: 'alice' },
-    { field: 'createdAt', operator: 'gte', value: '2024-01-01' },
-  ],
-});
-```
+Import from `@zeroxsolutions/db/utils`. The builders that turn a filter and an order into SQL are the base
+repository's own; a finder hands `filter` and `orderBy` to it unchanged.
 
 #### Supported Operators
 
@@ -368,90 +391,32 @@ All 15, as `filterOperatorSchema` declares them:
 
 A `%` or `_` in a text value is escaped, so it matches literally rather than as a wildcard.
 
-#### Relationship Filters
-
-A relationship named in a permit list is no column - its id sits in a foreign-key column instead, which
-`buildFilterConditions` cannot resolve on its own. Declare the permit through `permitsFor`'s own
-`relationship(name, operators)` (`@zeroxsolutions/query`), then hand `columnResolver` the foreign-key
-column under that same name in `resolvers`:
-
-```ts
-import { permitsFor } from '@zeroxsolutions/query';
-import { buildFilterConditions, columnResolver } from '@zeroxsolutions/db/utils';
-
-const placesQueryPermits = permitsFor(placeAttributes, { relationships: places.relationships }).relationship('region', [
-  'equals',
-  'in',
-]);
-
-const condition = buildFilterConditions({
-  table: places,
-  filter: query.filter,
-  resolvers: { region: columnResolver(places.regionId) },
-});
-```
+### relationsOf
 
-`columnResolver` answers `equals` and `in` - the only two operators a relationship filter grants -
-comparing the id against the column it closes over, and throws on any other operator.
-
-- `relationshipsOf(schema, '<table export>')` - the relations the schema declares on that table, as the map
-  `permitsFor(schema, { relationships })` takes, so a relationship filter names a relation the schema holds.
-  Throws on a key that is no table export (a table's SQL name is not one).
-
-### Order Builder
-
-```ts
-import { buildOrderBy } from '@zeroxsolutions/db/utils';
-
-const clauses = buildOrderBy(users, [
-  { field: 'createdAt', direction: 'desc' },
-  { field: 'name', direction: 'asc' },
-]);
-```
-
-`buildOrderBy` translates exactly the clauses it is given and appends no key, so it can build part of
-an order one clause at a time. A read that pages over its result owes itself a unique last clause.
-
-### Field Whitelist Guard
-
-Reject a `filter`/`sort` on any field outside a listable entity's whitelist **before** building SQL, so a
-client can never filter or order by a hidden column (e.g. an access code). `QueryableFields<TSelect>` is keyed
-to the row's `$inferSelect` type, so a renamed/removed column fails typecheck at the whitelist. The guard is
-transport-agnostic - it throws a plain `Error` subclass (`InvalidQueryFilter` / `InvalidQuerySort`) carrying
-only the offending field name; the calling service maps each error **type** to its HTTP status/code at its
-own transport.
-
-```ts
-import { assertQueryableFields, InvalidQueryFilter, type QueryableFields } from '@zeroxsolutions/db/utils';
-
-const USERS_QUERYABLE = {
-  filterable: ['name', 'createdAt'],
-  sortable: ['name', 'createdAt'],
-} as const satisfies QueryableFields<typeof users.$inferSelect>;
-
-// In a repository finder, before building SQL:
-assertQueryableFields(query, USERS_QUERYABLE); // throws InvalidQueryFilter / InvalidQuerySort on a hidden field
-```
+`relationsOf(schema, '<table export>')` answers the relations the schema declares on that table, each with the type
+its fieldset is keyed by (its table's SQL name), its primary key, and its own relations, read when a path walks into
+them. A permit list carries it as `relationships`, `permitsFor` checks a relationship filter's name against it, and
+`findOptionsOf` in `@zeroxsolutions/jsonapi` finds an included relation's fieldset through it. It throws on a key that
+is no table export (a table's SQL name is not one).
 
 ### Reading the query off a request
 
-This package ships **no** query schema. Parse the request with
-[`@zeroxsolutions/query`](../query) and hand its result straight to a finder - the
-member names line up (`offset` / `limit` / `sort` / `filter` / `fields` / `include`), so nothing renames anything:
+This package ships **no** query schema and knows no wire format. Parse the request with
+[`@zeroxsolutions/query`](../query), and turn the guarded query into finder options with `findOptionsOf` from
+[`@zeroxsolutions/jsonapi`](../jsonapi):
 
 ```ts
 import { collectionQuerySchema } from '@zeroxsolutions/query';
+import { findOptionsOf } from '@zeroxsolutions/jsonapi';
 
 createRoute({ request: { query: collectionQuerySchema(usersQueryPermits) } });
-const query = c.req.valid('query');
-const [rows, total] = await usersRepository.findAllAndCount(
-  buildFilterConditions({ table: users, filter: query.filter }),
-  query,
+const [rows, total] = await usersRepository.findAllAndCountByTenantId(
+  tenantId,
+  findOptionsOf(c.req.valid('query'), usersQueryPermits),
 );
 ```
 
-Pass `filterItem: filterValueSchema` in the spec so the parsed clauses are the ones this package's
-builders accept. A test in `utils/filter.spec.ts` pins the absence of a second query shape.
+Pass `filterItem: filterValueSchema` in the permits so the parsed clauses are the ones this package's finders accept.
 
 ### Omit Constants
 
@@ -470,15 +435,6 @@ import { defaultInsertOmit } from '@zeroxsolutions/db/utils';
 type InsertUser = Omit<typeof users.$inferInsert, keyof typeof defaultInsertOmit>;
 ```
 
-### Pagination Constants
-
-```ts
-import { DEFAULT_PAGE_SIZE, DEFAULT_OFFSET, MAX_PAGE_SIZE } from '@zeroxsolutions/db/utils';
-// DEFAULT_PAGE_SIZE = 20
-// DEFAULT_OFFSET    = 0
-// MAX_PAGE_SIZE     = 100
-```
-
 ---
 
 ## Testing Seam