cvx-kit 0.1.12 → 0.1.14

package/docs/oxlint.md

@@ -11,7 +11,8 @@ library authoring. The five architecture rules below were added in 0.1.6. See `u
 ## Configuration
 
 Install Oxlint as a development dependency and load the plugin in
-`.oxlintrc.json`. The root README includes a configuration enabling all rules.
+`.oxlintrc.json`. The root README includes a configuration enabling all rules. The coverage table
+below lists all 23 rule names.
 Loading a plugin does not enable its rules. For example:
 
 ```json
@@ -44,28 +45,31 @@ offer automatic fixes for architectural moves.
 
 Every name below has the `cvx/` prefix in lint configuration.
 
-| Rule                           | Detects                                                                                                                                                                                               | Documentation                                   |
-| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
-| `project-structure`            | Root folder allowlist, domain ownership, colocated runnable tests, misplaced tests, symlinks, parse failures, runtime domain-module cycles, and shared implementations with only one domain consumer. | Folder structure and Tests                      |
-| `root-wiring-only`             | Unknown root files without a component facade, root function declarations, nondelegating callbacks, branches, loops, direct writes/network calls, and inline root schema construction.                | Root files                                      |
-| `application-orchestration`    | Files without two domain dependencies, provider construction, external runtime dependencies, database access, validator construction, and business branches.                                          | Module grain                                    |
-| `internal-function-ownership`  | Internal/system registrations at root, in public API adapters, or in domain/shared.                                                                                                                   | Folder structure                                |
-| `domain-file-responsibilities` | Impure rules, query writes/mutations, database access in declarative files, misplaced direct external I/O, and imports that violate these roles.                                                      | File anatomy                                    |
-| `root-facade-ownership`        | `createAuthFunctions`, `createTriggers`, and `new Foundation` outside their root files, or repeated in one file.                                                                                      | `conventions.md`, Root files                    |
-| `no-raw-builders`              | Runtime imports of raw Convex builders outside `functions.ts`; namespace calls to raw generic builders.                                                                                               | `auth.md`; `llms.md`, Non-negotiable rules      |
-| `no-handwritten-references`    | Calls to Convex `makeFunctionReference`, including import aliases.                                                                                                                                    | `conventions.md`, Import rules                  |
-| `domain-import-boundaries`     | Reverse dependencies into `api/`, domain imports of `application/`, forbidden sibling imports, and API adapters importing another domain module.                                                      | `conventions.md`, Module grain and Import rules |
-| `public-functions-in-api`      | Calls to root `auth*`, `role*`, or `admin*` constructors outside `api/`.                                                                                                                              | `conventions.md`, Folder structure              |
-| `thin-api-adapters`            | `if`, `switch`, ternary branches, top-level private helpers, and direct `ctx.db` writes in `api/`.                                                                                                    | `conventions.md`, The adapter file              |
-| `no-inline-enums`              | Literal arrays passed to imported Zod `enum`. Use named vocabulary tuples.                                                                                                                            | `conventions.md`, Vocabularies                  |
-| `no-unbounded-reads`           | Direct `ctx.db.query(...).collect()` chains and `ctx.include(...).resolve()` chains in host code.                                                                                                     | `llms.md`, Bounded reads; `zod-table.md`        |
-| `no-manual-timestamps`         | Explicit `createdAt`/`updatedAt` fields in object literals passed to direct `ctx.db` writes.                                                                                                          | `triggers.md`                                   |
-| `component-boundaries`         | Local portable components importing host/sibling files; host imports bypassing component client facades; private package component subpaths.                                                          | `architecture.md`, Injection, not import        |
-| `no-component-env`             | Direct `process.env` access, process import aliases, environment destructuring, and named env imports inside local portable components.                                                               | `conventions.md`, Import rules                  |
-| `schema-file-boundaries`       | Host `defineTable`, misplaced `defineSchema` or kit table constructors, and misplaced `.table.index/searchIndex/vectorIndex` chains.                                                                  | `conventions.md`, Shapes and topology           |
-| `no-internal-reexports`        | Re-exports and import-then-export aliases inside `convex/`.                                                                                                                                           | `conventions.md`, Universal file order          |
-| `public-api-first`             | Private function declarations before the last export.                                                                                                                                                 | `conventions.md`, Universal file order          |
-| `named-private-helpers`        | Top-level private arrow/function-expression variables.                                                                                                                                                | `conventions.md`, Universal file order          |
+| Rule                           | Detects                                                                                                                                                                                               | Documentation                                       |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| `project-structure`            | Root folder allowlist, domain ownership, colocated runnable tests, misplaced tests, symlinks, parse failures, runtime domain-module cycles, and shared implementations with only one domain consumer. | Folder structure and Tests                          |
+| `root-wiring-only`             | Unknown root files without a component facade, root function declarations, nondelegating callbacks, branches, loops, direct writes/network calls, and inline root schema construction.                | Root files                                          |
+| `application-orchestration`    | Files without two domain dependencies, provider construction, external runtime dependencies, database access, validator construction, and business branches.                                          | Module grain                                        |
+| `internal-function-ownership`  | Internal/system registrations at root, in public API adapters, or in domain/shared.                                                                                                                   | Folder structure                                    |
+| `domain-file-responsibilities` | Impure rules, query writes/mutations, database access in declarative files, misplaced direct external I/O, and imports that violate these roles.                                                      | File anatomy                                        |
+| `root-facade-ownership`        | `createAuthFunctions`, foundation factories, `createTriggers`, `defineRelations`, and `createQueryEngine` outside their root facades, or repeated in one file.                                        | `conventions.md`, Root files                        |
+| `no-raw-builders`              | Runtime imports of raw Convex builders outside `functions.ts`; namespace calls to raw generic builders.                                                                                               | `auth.md`; `llms.md`, Non-negotiable rules          |
+| `no-handwritten-references`    | Calls to Convex `makeFunctionReference`, including import aliases.                                                                                                                                    | `conventions.md`, Import rules                      |
+| `domain-import-boundaries`     | Reverse dependencies into `api/`, domain imports of `application/`, forbidden sibling imports, and API adapters importing another domain module.                                                      | `conventions.md`, Module grain and Import rules     |
+| `public-functions-in-api`      | Calls to root `auth*`, `role*`, or `admin*` constructors outside `api/`.                                                                                                                              | `conventions.md`, Folder structure                  |
+| `thin-api-adapters`            | `if`, `switch`, ternary branches, top-level private helpers, and direct `ctx.db` writes in `api/`.                                                                                                    | `conventions.md`, The adapter file                  |
+| `no-inline-enums`              | Literal arrays passed to imported Zod `enum`. Use named vocabulary tuples.                                                                                                                            | `conventions.md`, Vocabularies                      |
+| `no-unbounded-reads`           | Recognized unbounded database/stream/relationship reads and eligibility `.filter()` calls after bounded take/execute/paginate results.                                                                | `llms.md`, Bounded reads; `zod-table.md`            |
+| `no-manual-timestamps`         | Explicit `createdAt`/`updatedAt` fields in object literals passed to direct `ctx.db` writes.                                                                                                          | `triggers.md`                                       |
+| `component-boundaries`         | Local portable components importing host/sibling files; host imports bypassing component client facades; private package component subpaths.                                                          | `architecture.md`, Injection, not import            |
+| `no-component-env`             | Direct `process.env` access, process import aliases, environment destructuring, and named env imports inside local portable components.                                                               | `conventions.md`, Import rules                      |
+| `schema-file-boundaries`       | Host `defineTable`, misplaced `defineSchema` or kit table constructors, and misplaced `.table.index/searchIndex/vectorIndex` chains.                                                                  | `conventions.md`, Shapes and topology               |
+| `no-internal-reexports`        | Re-exports and import-then-export aliases inside `convex/`.                                                                                                                                           | `conventions.md`, Universal file order              |
+| `public-api-first`             | Private function declarations before the last export.                                                                                                                                                 | `conventions.md`, Universal file order              |
+| `named-private-helpers`        | Top-level private arrow/function-expression variables.                                                                                                                                                | `conventions.md`, Universal file order              |
+| `no-manual-id-projection`      | Adding `id`/`_id` to a recognized table DTO through object spreads or property assignments.                                                                                                           | Public DTO parameters in `zod-table.md`             |
+| `no-copied-pagination`         | Zod/native validator objects copying `numItems` + `cursor` or `page` + `isDone` + `continueCursor`.                                                                                                   | Pagination options in `zod-table.md`; `querying.md` |
+| `reserved-domain-file-anatomy` | Reserved domain files without their expected declarative schema/contracts/table or Command/Query registry shape.                                                                                      | Reserved domain files below                         |
 
 ## Allowed patterns
 
@@ -87,14 +91,114 @@ Every name below has the `cvx/` prefix in lint configuration.
 - `archivedAt` remains application-controlled. Singular `db.get` reads and
   bounded `execute`/`paginate` calls are allowed.
 
+## DTO and pagination diagnostics
+
+Enable the new diagnostics alongside the existing architecture rules:
+
+```json
+{
+	"rules": {
+		"cvx/no-manual-id-projection": "error",
+		"cvx/no-copied-pagination": "error",
+		"cvx/no-unbounded-reads": "error",
+		"cvx/root-facade-ownership": "error",
+		"cvx/root-wiring-only": "error",
+		"cvx/reserved-domain-file-anatomy": "error"
+	}
+}
+```
+
+### `no-manual-id-projection`
+
+Recognizes a table DTO projection/parse, including supported binding aliases,
+then reports adding `id` or `_id` by a spread or property assignment:
+
+```ts
+// Reported
+const output = { ...tasks.toPublicDto(row), _id: row._id }
+const parsed = tasks.publicDto.parse(input)
+parsed.id = row._id
+
+// Use the matching projection and return boundary
+const outputWithId = tasks.toPublicDto(row, true)
+const returns = tasks.dto(true)
+```
+
+The helper returns `_id`, not an `id` alias. For computed fields use the
+validated `extend`/`values` API described in [zod-table.md](./zod-table.md).
+The rule depends on recognized table/DTO provenance; it does not treat every
+object named `dto` as a kit boundary or prove all runtime projection paths safe.
+
+### `no-copied-pagination`
+
+Reports recognized `z.object`/Convex `v.object` shapes containing both `numItems`
+and `cursor`, or all three of `page`, `isDone`, and `continueCursor`:
+
+```ts
+// Reported
+const options = z.object({ numItems: z.number(), cursor: z.string().nullable() })
+const result = z.object({
+	page: z.array(tasks.publicDto),
+	isDone: z.boolean(),
+	continueCursor: z.string(),
+})
+
+// Table query input and relation-aware output
+const options = tasks.paginationOpts({ status: true })
+const result = relations.tables.tasks.pageDto({})
+```
+
+For ordinary native pagination, retain `paginationOptsValidator` (bridge through
+`convexToZod` when needed) or `paginated(tasks.dto())`. These preserve native
+validators instead of copying their current fields. Application-specific fields
+can extend the derived Zod object. Use the engine's `paginationOpts` for its
+selected filters and order; a native options validator alone supplies neither.
+
+### `no-unbounded-reads`
+
+The existing rule now follows recognized native, kit `include`, stream, and
+relationship read chains. It reports unbounded `collect()`/`resolve()` where
+supported provenance is known, and `.filter()` on recognized bounded results:
+
+```ts
+// Reported: eligible rows outside the first 25 can be missed
+const rows = await ctx.db.query('tasks').take(25)
+const eligible = rows.filter((task) => task.status === 'open')
+
+// Put eligibility into the query before page filling
+const page = await querying(ctx).tasks.where({ status: 'open' }).paginate(args)
+```
+
+Choose an indexed native constraint where appropriate, or express the predicate
+through the querying engine. Many relationships use bounded pages and separate
+continuation endpoints. There is no automatic predicate-movement fix: moving a
+predicate can change authorization, ordering, and continuation semantics.
+
+### Relation and engine facade ownership
+
+`root-facade-ownership` requires `defineRelations` in `convex/relations.ts` and
+`createQueryEngine` in `convex/querying.ts`, each configured once. The same rule
+continues to enforce auth, triggers, and foundation facades.
+
+`root-wiring-only` and the whole-project checker permit these root files only
+as narrow declarative factory configurations. `relations.ts` can import domain
+schema/table declarations (including the domain table assembly); `querying.ts`
+can import domain query/contract modules where permitted. Neither file is a
+place for endpoint handlers, business branches, or direct database operations.
+Domain contracts derive validators, domain Query registries own handlers, and
+`api/` adapters delegate through authenticated constructors. See
+[querying.md](./querying.md) and [conventions.md](./conventions.md).
+
 ## What still needs review and tests
 
 These are syntax and lexical-binding checks, not whole-program validation.
 Import-boundary rules resolve relative imports and tsconfig aliases (including
 extended configs) using the package resolver. Symlinked source is rejected by
 the project scan. Computed import paths are not resolved. Named import aliases and namespaces are recognized where documented;
-arbitrary variable reassignment, wrapper functions, destructured database
-methods, and calls split across variables are not traced. Database checks
+General variable reassignment, arbitrary wrappers, and destructured database
+methods are not whole-program traced. DTO/read checks do follow supported local
+initializers, aliases, awaited results, and recognized helper chains; unrelated
+user functions and unknown provenance remain outside that bounded analysis. Database checks
 recognize the documented `ctx.db` member shape, not its runtime type.
 
 The plugin does not prove DTO redaction, complete command/audit coverage,

package/docs/querying.md

@@ -0,0 +1,293 @@
+# `cvx-kit/querying` — typed, authorized stream pagination
+
+Declare relationships with `cvx-kit/relations`, configure one query engine, then
+paginate with a small declarative chain. The engine runs streams and relationship
+lookups in the caller's Convex query transaction. Filtering determines eligible
+parents before they fill a page. `include` and native `paginated(dto)` remain
+independent APIs.
+
+## Declare tables and indexes
+
+Keep shapes in `domain/<module>/schema.ts` and native indexes in its `table.ts`.
+These examples put tasks, labels, and their junction in one owning module.
+
+```ts
+// convex/domain/tasks/schema.ts
+import { z } from 'zod'
+import { zodTable } from 'cvx-kit/zod-table'
+
+export const tasks = zodTable(
+	'tasks',
+	(id) => ({
+		title: z.string(),
+		department: z.string(),
+		status: z.string(),
+		priority: z.number(),
+		reference: id('tasks').nullable().optional(),
+	}),
+	{ publicFields: ['title', 'department', 'status', 'priority'] },
+)
+
+export const labels = zodTable(
+	'labels',
+	() => ({
+		name: z.string(),
+	}),
+	{ publicFields: ['name'] },
+)
+
+export const edges = zodTable(
+	'edges',
+	(id) => ({
+		task: id('tasks'),
+		label: id('labels'),
+	}),
+	{ publicFields: [] },
+)
+```
+
+```ts
+// convex/domain/tasks/table.ts
+import { tasks, labels, edges } from './schema'
+
+export const tables = {
+	tasks: tasks.table.index('by_department_status', ['department', 'status']),
+	labels: labels.table,
+	edges: edges.table.index('by_task', ['task']),
+}
+```
+
+Assemble those table definitions in the application's root schema. Declare every
+index used by a relationship before compiling the relation registry.
+
+## Declare relationships once
+
+```ts
+// convex/relations.ts
+import { defineRelations } from 'cvx-kit/relations'
+import './domain/tasks/table'
+import { tasks, labels, edges } from './domain/tasks/schema'
+
+export const relations = defineRelations({ tasks, labels, edges }, (r) => ({
+	tasks: {
+		referenceTask: r.one.tasks({ from: r.tasks.reference, to: r.tasks._id }),
+		labels: r.many.labels({
+			from: r.tasks._id.through(r.edges.task),
+			to: r.labels._id.through(r.edges.label),
+		}),
+	},
+}))
+```
+
+A direct one edge uses `r.one.target({ from, to })`; a direct many edge uses
+`r.many.target({ from, to })`. For example, with a stored `labels.task` foreign
+key and a supporting `by_task` index on labels:
+
+```ts
+r.many.labels({ from: r.tasks._id, to: r.labels.task })
+```
+
+Relationship names distinguish multiple references to the same table. Self
+references and junctions are supported. Tables must be object-shaped `zodTable`
+or `tenantTable` boundaries; variant tables are outside this API. Declarations
+are validated against table ownership, field compatibility, and supporting
+indexes. Convex does not infer relationships; this registry supplies them.
+
+## Configure the engine and authentication
+
+```ts
+// convex/querying.ts
+import { createQueryEngine } from 'cvx-kit/querying'
+import schema from './schema'
+import { relations } from './relations'
+import { cursor } from './functions'
+
+export const querying = createQueryEngine({ schema, relations, cursor })
+```
+
+The application's `functions.ts` facade configures `createAuthFunctions`,
+including its membership resolution and effective read/tenancy policies. Call
+`querying(ctx)` with a query context supplied by that facade's `authQuery`.
+The engine consumes the private managed reader capability installed there and
+rechecks composed authorization for parents, junctions, targets, and continuation
+reads. The example declarations do not establish access policy on their own.
+See [auth.md](./auth.md) and [tenancy.md](./tenancy.md) for policy setup.
+
+Unknown contexts fail closed with `UNMANAGED_QUERY_CONTEXT`. Mutation and action
+contexts are unsupported. A host with another auth system can centrally configure
+`trustedAdapter`; it must attest the query reader, effective policy, and security
+scope. Do not expose adapter selection to endpoint arguments.
+
+`cursor` has `{ version, currentKeyId, keys }`. `keys` maps key IDs to server-only
+64-byte `Uint8Array` secrets; `currentKeyId` names the key used for new tokens.
+Load real secrets through server configuration, never from clients or a constant
+fixture key. Keep prior keys during rotation to preserve existing cursors.
+The default codec uses authenticated AES-SIV encryption; there is no plaintext
+fallback. Identical bound payloads reveal equality.
+
+## Define input and result contracts
+
+```ts
+// Inside convex/domain/tasks/contracts.ts
+const input = relations.tables.tasks.paginationOpts({
+	department: true,
+	status: true,
+	priority: true,
+	referenceTask: { status: true },
+	labels: { name: true },
+})
+const result = relations.tables.tasks.pageDto({
+	referenceTask: true,
+	labels: true,
+})
+```
+
+`paginationOpts(selection)` extends native Convex pagination options with optional
+`filters` and global `order: 'asc' | 'desc'`. The selection permits client filters;
+it does not change public output or grant access. The result selection must
+match `.with(...)`. `.pageDto({})` returns a native page of the table's public
+DTOs including branded `_id`. One relationships return a public DTO or `null`;
+many relationships return their own bounded native pages. Missing and unreadable
+targets have the same public result. Duplicate junction occurrences remain in
+output, even when target reads are memoized.
+
+For scalar-only input, use `tasks.paginationOpts({ status: true })`. Both forms
+are Zod objects and support `.extend(...)` for endpoint-specific arguments.
+Use the contracts through your domain Query registry and keep public auth
+registration in `api/<entity>.ts`; see [domain-contracts.md](./domain-contracts.md).
+
+## Query and filter
+
+```ts
+// Inside an authenticated domain Query handler
+const department = args.filters?.department
+const indexCondition = typeof department === 'string' ? department : undefined
+const page = await querying(ctx)
+	.tasks.where({ status: 'open' })
+	.when(indexCondition, 'by_department_status')
+	.with({ referenceTask: true, labels: true })
+	.paginate(args)
+```
+
+`.where(spec)` adds server-owned constraints, combined with client filters by
+AND. Use it for mandatory business constraints; effective auth policy still
+controls access. `.with(selection)` chooses related output. A relation can be
+used as an eligibility filter without also including it in output. A parent
+relationship predicate does not filter the nested output page: it determines
+whether the parent is eligible. Child-page filters are a separate query input.
+
+Example client args for the contract above:
+
+```ts
+{
+  numItems: 25,
+  cursor: null,
+  order: 'desc',
+  filters: {
+    department: 'engineering',
+    priority: { gte: 2, lt: 5 },
+    labels: { some: { name: 'urgent' } },
+    not: { status: 'blocked' },
+  },
+}
+```
+
+Scalar predicates accept direct equality or operator objects with `eq`, `in`,
+and, for supported range types, `gt`, `gte`, `lt`, and `lte`. Optional fields
+also support `exists`. `and` and `or` contain nonempty arrays of predicates;
+`not` contains one predicate. Use `fields: { ... }` to address scalar fields
+whose names collide with grammar keys such as `and`, `or`, `not`, or `fields`.
+One relationships accept a nested predicate or `null`; many relationships use
+`some` or `none` over authorized targets. Unknown fields and incompatible scalar
+values/operators fail validation. Filter depth is at most four, the whole tree
+has at most 256 nodes, and an `in` list contains at most 100 values.
+
+## Conditional indexes and ordering
+
+`.when(value, 'index_name')` selects the first present condition. `false`, `0`,
+and `''` are present; `null` and `undefined` are absent. The condition chooses an
+index but does not bind its fields: validated filters and `.where(...)` supply
+the bindings. An incompatible explicit index fails instead of silently scanning.
+Relationship traversal retains its mandatory foreign-key prefix.
+
+Without an explicit choice, the planner selects the longest usable equality
+prefix, with stable index-name ordering for ties and creation-time fallback.
+OR branches contribute only guaranteed common bindings. `order: 'desc'` reverses
+the selected native index order; it does not sort by an arbitrary field.
+
+## Continue relationship pages
+
+Return many relationships as pages, then use a separate authenticated endpoint
+for their next page. Validate `parent` with `tasks.schema.shape._id` and use the
+related table's pagination contract:
+
+```ts
+const input = relations.tables.labels
+	.paginationOpts({ name: true })
+	.extend({ parent: tasks.schema.shape._id })
+const result = relations.tables.labels.pageDto({})
+
+// Inside the child Query handler
+const { parent, ...options } = args
+return querying(ctx).tasks.relation(parent, 'labels').paginate(options)
+```
+
+The client sends the parent ID and the nested page's `continueCursor`, preserving
+its original order and output selection. For the parent example above that means
+`order: 'desc'`, selection `{}`, and no child filters on resume; adding a `name`
+filter would change the binding and reject that cursor. A new child traversal
+with `cursor: null` can establish its own filters. Typed
+paths can traverse several declared edges to a many relationship. Each request
+rechecks the parent path and current authorization; a child token cannot be
+replayed under another parent.
+
+Root, child, split, and end cursors bind filters, output selection, index, order,
+ancestry, principal/tenant/security scope, and registry/policy/engine versions.
+Changing page size alone remains valid. Treat tokens as opaque; preserve native
+`isDone`, `continueCursor`, and optional page-status/split metadata. Permission
+changes are rechecked on resume. Native `endCursor` supports bounded partitions.
+
+## Central limits and operational behavior
+
+`createQueryEngine` also accepts `maxPageSize`, `budgets`, `policyVersion`,
+`engineVersion`, and `trustedAdapter`. These belong in central configuration,
+not per-endpoint filter/project callbacks. Page sizes are positive integers up
+to 100; `maxPageSize` can lower that ceiling. Shared request budgets cover read
+operations, index ranges, raw candidates, document bytes, fan-out, traversal
+depth, and memo entries, including managed policy reads. Native request read
+limits may lower ceilings. Output relationship depth is at most four.
+
+If eligibility cannot be established within the budget, execution throws
+`MANAGED_READ_BUDGET`; it does not return a misleading exhausted page or conclude
+that a negative relationship predicate matched. Policy errors propagate rather
+than turning into eligible rows. Memoization is request-local and preserves
+junction multiplicity. Relationships can require many database reads; one public
+query does not imply one physical read. Document accounting is an application
+bound, not a measurement of Convex storage/index/prefetch I/O.
+
+Arbitrary async predicates, custom projections/sorts, mutation/action execution,
+search/vector optimization, and global caching are outside this API. Index
+selection reduces candidates where possible; filtering every supported scalar
+field does not guarantee an efficient index for every filter combination.
+
+## Migration and verification
+
+Use `toPublicDto(row, true)` with `dto(true)` instead of manual ID spreads.
+Replace copied pagination schemas with table/registry helpers. Move eligibility
+predicates before bounded page filling, and replace unbounded relationship
+collection with declared many pages and child continuation. See the diagnostics
+and examples in [oxlint.md](./oxlint.md).
+
+The [packed example](../../test/fixture-packed-querying/convex/) contains complete
+schema, relation, engine, contract, Query-registry, auth-adapter, and child-endpoint
+wiring. `bun run test:package:querying` exercises strict installed and minimum-peer
+consumers, all consumer rules, and multi-entity/filter/order continuation tests.
+The local native smoke runner exercises registered Convex validators and cursors;
+these checks do not establish hosted production performance.
+
+Run `bunx vp test run test/querying-relations-stress.test.ts --silent=false` to
+report per-page p10, p50, and p99 latency for each filter/order/page-size case,
+plus an aggregate for duplicate child continuations. Reports include sample
+counts and use nearest-rank percentiles. A small sample's p99 is its maximum;
+the measurements include `convex-test` and instrumentation overhead. Read
+counters and ordered-result assertions remain separate from latency measurements.

package/docs/zod-table.md

@@ -49,19 +49,21 @@ unregistered foreign ID and does not throw; peer installation prevents the
 supported package graph from creating that ambiguity. Verify critical ID
 validators retain `kind === 'id'` and the expected `tableName` after installation.
 
-| Property                                     | What it is                                           | Where you use it               |
-| -------------------------------------------- | ---------------------------------------------------- | ------------------------------ |
-| `table`                                      | `defineTable(...)` from the storage shape            | `convex/schema.ts`             |
-| `storage`                                    | zod object of the raw row (no `_id`/`_creationTime`) | validating rows                |
-| `schema`                                     | `storage` + `_id` + `_creationTime`                  | full-document validation       |
-| `insertSchema`                               | storage minus timestamps minus `serverFields`        | mutation args                  |
-| `updateSchema`                               | `insertSchema.partial()`                             | patch mutation args            |
-| `commandInput`                               | strict pick of `commandFields`                       | command protocol inputs        |
-| `publicDto`                                  | strict pick of `publicFields`                        | query return validators        |
-| `toPublicDto(row)`                           | projects **and re-parses** a row into the DTO        | query handlers                 |
-| `insert(omit?)` / `update(omit?)`            | schema with per-callsite field omission              | specialized mutations          |
-| `tools.insert` / `tools.update` / `tools.id` | ready-made LLM tool input schemas                    | agent tool definitions         |
-| `tableName`                                  | the literal table name                               | indexes, triggers registration |
+| Property                                     | What it is                                             | Where you use it               |
+| -------------------------------------------- | ------------------------------------------------------ | ------------------------------ |
+| `table`                                      | `defineTable(...)` from the storage shape              | `convex/schema.ts`             |
+| `storage`                                    | zod object of the raw row (no `_id`/`_creationTime`)   | validating rows                |
+| `schema`                                     | `storage` + `_id` + `_creationTime`                    | full-document validation       |
+| `insertSchema`                               | storage minus timestamps minus `serverFields`          | mutation args                  |
+| `updateSchema`                               | `insertSchema.partial()`                               | patch mutation args            |
+| `commandInput`                               | strict pick of `commandFields`                         | command protocol inputs        |
+| `publicDto`                                  | strict pick of `publicFields`                          | query return validators        |
+| `dto(options?)`                              | public return schema with optional ID and extensions   | query return validators        |
+| `toPublicDto(row)`                           | projects **and re-parses** a row into the DTO          | query handlers                 |
+| `paginationOpts(selection)`                  | native pagination options, selected filters, and order | query input validators         |
+| `insert(omit?)` / `update(omit?)`            | schema with per-callsite field omission                | specialized mutations          |
+| `tools.insert` / `tools.update` / `tools.id` | ready-made LLM tool input schemas                      | agent tool definitions         |
+| `tableName`                                  | the literal table name                                 | indexes, triggers registration |
 
 ## Redaction is runtime, not just types
 
@@ -82,6 +84,84 @@ export const get = authQuery({
 })
 ```
 
+## Public DTO parameters
+
+`publicDto` is the strict Zod schema selected by `publicFields`; it takes no
+parameters. Use `dto(...)` to derive a return schema and `toPublicDto(row, ...)`
+to project a row with the same options. These methods are also available on
+`tenantTable` boundaries.
+
+```ts
+documents.toPublicDto(row) // publicFields only
+documents.toPublicDto(row, false) // same default projection
+documents.toPublicDto(row, true) // publicFields plus _id
+documents.toPublicDto(row, { _id: true }) // explicit equivalent
+
+const withoutId = documents.dto() // same boundary as publicDto
+const withId = documents.dto(true) // branded Id<'documents'>
+const explicit = documents.dto({ _id: true })
+```
+
+Including `_id` requires a row containing an ID and validates it through the
+table's ID schema. It does not expose `_creationTime`, tenant metadata, or other
+storage fields. Do not spread an ID onto a parsed DTO manually; use the matching
+`dto(true)` return validator.
+
+Computed fields need both a schema and explicitly supplied values:
+
+```ts
+const extend = { url: z.url() }
+const returnSchema = documents.dto({ _id: true, extend })
+
+const output = documents.toPublicDto(row, {
+	_id: true,
+	extend,
+	values: { url: `https://example.test/documents/${row._id}` },
+})
+returnSchema.parse(output)
+```
+
+`extend` is a map of field names to Zod validators, not an `extendFields` wrapper.
+`values` belongs only to the projector; `dto(...)` describes the result. Extension
+values are parsed as a strict object: missing required fields, unknown values,
+and invalid values fail. Values are never copied implicitly from storage.
+
+Extensions cannot replace public fields or use `_id`, `_creationTime`, `tenant`,
+`createdAt`, `updatedAt`, `archivedAt`, or `__proto__`. Their schemas must validate
+without changing values: transforms, pipes, coercion, preprocess, defaults,
+catches, and overwrites are rejected, including inside nested schemas.
+Refinements must not mutate their input. Existing public-field schemas retain
+their existing parsing behavior.
+
+## Pagination options
+
+Select filterable scalar fields independently of the public DTO mask:
+
+```ts
+const input = documents.paginationOpts({ title: true, ownerId: true })
+const args = input.parse({
+	numItems: 25,
+	cursor: null,
+	order: 'desc',
+	filters: { title: 'Proposal' },
+})
+```
+
+The helper extends Convex's native pagination options with optional `filters`
+and `order: 'asc' | 'desc'`. It returns a Zod object that can be used directly as
+query args or extended with endpoint-specific fields. `numItems` must be a
+positive integer at most 100; engine configuration may lower that ceiling.
+Unknown filter fields fail. Stored scalar fields, including explicitly selected
+server-owned fields and IDs, can be filterable even when absent from the DTO.
+Arrays, objects, and other unsupported non-scalar fields cannot be selected.
+This schema creates no authorization policy by itself.
+
+For relationship filters and paginated public output, use
+`relations.tables.documents.paginationOpts(selection)` and `.pageDto(selection)`.
+See [querying.md](./querying.md) for declarations, conditional indexes, filters,
+authorization, and child-page continuation. Existing native pagination can keep
+using `paginated(dto)`; the querying engine is independent of `include`.
+
 ## Opinionated timestamps
 
 Every `zodTable` bakes in three optional, **server-owned** fields:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cvx-kit",
-	"version": "0.1.12",
+	"version": "0.1.14",
 	"description": "Reusable Convex application kit: foundation kernels, approvals component, zod table boundaries, WorkOS-backed auth function constructors, and audited command protocol.",
 	"keywords": [
 		"component",
@@ -30,6 +30,14 @@
 			"types": "./dist/zod-table.d.mts",
 			"import": "./dist/zod-table.mjs"
 		},
+		"./relations": {
+			"types": "./dist/relations-public.d.mts",
+			"import": "./dist/relations-public.mjs"
+		},
+		"./querying": {
+			"types": "./dist/querying.d.mts",
+			"import": "./dist/querying.mjs"
+		},
 		"./effect": {
 			"types": "./dist/effect.d.mts",
 			"import": "./dist/effect.mjs"
@@ -134,6 +142,7 @@
 		"test:package:oxlint": "bun run build && node scripts/test-packed-oxlint.mjs",
 		"test:package:effect": "bun run build && node scripts/test-packed-effect.mjs",
 		"test:package:auth": "bun run build && node scripts/test-packed-auth.mjs",
+		"test:package:querying": "bun run build && node scripts/test-packed-querying.mjs",
 		"test:package:smoke:effect": "bun run build && node scripts/smoke-packed-effect.mjs",
 		"test:package:smoke:bun": "bun scripts/smoke-packed-components.mjs bun",
 		"test:package:smoke:npm": "node scripts/smoke-packed-components.mjs npm",
@@ -145,6 +154,7 @@
 	},
 	"dependencies": {
 		"@convex-dev/workflow": "0.4.10",
+		"@noble/ciphers": "2.4.0",
 		"@oxlint/plugins": "1.87.0",
 		"@standard-schema/spec": "^1.1.0",
 		"convex-audit-log": "^0.2.0",