cvx-kit 0.1.15 → 0.1.16

package/docs/querying.md

@@ -1,329 +0,0 @@
-# `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'
-
-export const querying = createQueryEngine({ schema, relations })
-```
-
-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.
-
-Declare this engine once at module scope. It serves every registered table;
-`querying(ctx)` binds authorization and read accounting to the current request.
-Table fields, indexes, DTOs, and relationship metadata come from the schema and
-relation registry. No per-table engine declaration is needed.
-
-The engine loads cursor keys internally when pagination first runs. Set
-`CVX_QUERY_CURSOR_KEYS_JSON` to a JSON object mapping key IDs to 128 hexadecimal
-characters (64 secret bytes), and `CVX_QUERY_CURSOR_CURRENT_KEY_ID` to the ID
-used for new tokens. These are server environment variables, shared by all
-tables. Generate real secrets outside query execution and configure them through
-Convex environment settings; never put them in client arguments, source, or logs.
-Keep prior keys during rotation to preserve existing cursors. Changing environment
-configuration requires the engine to reload with the new deployment configuration.
-
-Engine declaration and auth registration do not read these variables. Missing or
-invalid configuration fails pagination before database reads. The codec's format
-version is internal. It uses authenticated AES-SIV encryption with 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
-
-The engine supplies default limits and cursor compatibility versions. Normal
-applications need only `{ schema, relations }`. Optional central overrides belong
-in the second argument:
-
-```ts
-export const querying = createQueryEngine(
-	{ schema, relations },
-	{
-		maxPageSize: 50,
-	},
-)
-```
-
-| Option           | Purpose                                                                | Default setup                                               |
-| ---------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------- |
-| `budgets`        | Lower shared read, byte, fan-out, depth, and memo ceilings             | Engine defaults                                             |
-| `maxPageSize`    | Lower the 100-item page ceiling                                        | 100                                                         |
-| `policyVersion`  | Invalidate old cursors after a policy semantic change                  | Internal default; current authorization is always rechecked |
-| `engineVersion`  | Override the engine compatibility identity                             | Internal default                                            |
-| `trustedAdapter` | Connect another auth system's query reader and policies                | Managed auth capability from `cvx-kit/auth`                 |
-| `cursor`         | Supply an explicit key ring, for custom secret management or migration | Server environment loader                                   |
-
-These are application-wide overrides, never endpoint arguments. Existing
-one-argument declarations with these fields still work for compatibility; move
-those fields to the second argument when migrating. To preserve pre-migration
-cursors, keep the existing explicit cursor version and key ring until those
-cursors have expired.
-
-Page sizes are positive integers up to 100. 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/tenancy.md

@@ -1,176 +0,0 @@
-# `cvx-kit/tenancy` — row-level security, with tenancy as an opt-in layer
-
-Row-level security and tenancy are **separate, composable features** of the
-same `security` config on `createAuthFunctions`:
-
-- **`security.rules` alone** — role-level / module-level RLS with no tenancy
-  at all: gate writes by role, freeze evidence tables, ownership-gate reads.
-  `defaultPolicy` stays `'allow'`; unlisted tables behave normally.
-- **`security.tenancy` alone** — pure tenant isolation from a table registry.
-- **Both** — rules are AND-composed with tenant isolation.
-
-A single-org app that only wants role-gated writes configures `rules` and
-never touches tenancy. Nothing below is required unless you opt into it.
-
-Multi-tenancy itself is a structural machine, not a per-handler
-convention. The model: **tenant = the identity provider's organization id**,
-stamped as a server-owned `tenant` string field on every tenant-scoped row,
-always derived from the verified identity — never accepted as an argument.
-Isolation is defense-in-depth; each layer covers a hole in the previous one:
-
-1. **Schema** — `tenantTable` injects the field and strips it from every
-   write boundary.
-2. **Row-level security** — deny-default rules generated mechanically from
-   one table registry, wrapped into the auth constructors.
-3. **Triggers** — a post-image invariant forbids tenant reassignment (RLS
-   authorizes against the pre-image only).
-4. **Reference guards** — client-supplied ids re-verify ownership without
-   disclosing existence.
-
-Single-org apps skip all of this: every piece is opt-in, and
-`createAuthFunctions` without a `security` config behaves exactly as before.
-
-## The registry is the design
-
-One list of table names drives everything. Adding a table to the registry is
-the entire onboarding — there is no second per-table step to forget:
-
-```ts
-// convex/tenancy.ts (or alongside triggers.ts)
-export const TENANT_TABLES = ['<entities>', '<others>'] as const
-```
-
-- `security.tenancy.tables: TENANT_TABLES` → RLS rules generated per table
-- `tenantOwnership(triggers, ...TENANT_TABLES)` → reassignment guard per table
-- each listed table is declared with `tenantTable(...)` in its module
-
-Recommended architecture test: assert every `tenantTable` in the codebase
-appears in `TENANT_TABLES`, and vice versa.
-
-## Wiring
-
-```ts
-// domain/<module>/schema.ts — tenant injected at the schema boundary
-export const <entities> = tenantTable('<entities>', (id) => ({
-  name: z.string(), ownerId: id('users'),
-}), { publicFields: ['name'] })
-// tenant: excluded from insertSchema/updateSchema/commandInput,
-// in publicDto only if explicitly allowlisted
-
-// domain/<module>/table.ts — every index tenant-prefixed
-<entities>: <entities>.table.index('by_tenant', ['tenant'])
-                            .index('by_tenant_owner', ['tenant', 'ownerId'])
-
-// convex/triggers.ts
-tenantOwnership(triggers, ...TENANT_TABLES)
-
-// convex/functions.ts
-createAuthFunctions<DataModel>({
-  ...,
-  security: {
-    tenancy: {
-      tables: TENANT_TABLES,
-      // optional; defaults to bundle.org.organizationId
-      resolve: (bundle) => bundle.org.organizationId,
-    },
-    // role-level security, AND-composed with tenant isolation
-    rules: (bundle) => ({
-      '<entities>': { modify: async () => bundle.role === '<privileged>' },
-    }),
-    // defaults to 'deny' when tenancy is configured
-    defaultPolicy: 'deny',
-  },
-})
-```
-
-## What the constructors do with it
-
-- Every authenticated ctx gains **`ctx.tenant`** (also on the frozen bundle) —
-  resolved via `security.tenancy.resolve`, defaulting to the organization id.
-  Actions re-derive it from the live-verified membership.
-- **Queries** get a wrapped reader: rows failing `read` are invisible —
-  filtered from every `get`/`query`, even a full table scan.
-- **Mutations** wrap triggers first, then the RLS writer — `insert`/`modify`
-  failing a rule throws. Order matters and is handled for you.
-- **`system*` constructors stay unwrapped** — trusted internal paths reach
-  every table. This is deliberate: schedulers and callbacks receive the
-  server-derived tenant as data, never as authority.
-- With tenancy configured, `defaultPolicy` defaults to **deny**: tables
-  outside the registry are unreachable from `auth*`/`role*`/`admin*`
-  functions. Global/platform tables are reached from `system*` paths, or by
-  explicitly granting rules for them.
-
-Handlers stamp inserts from the ctx — the schema forbids clients supplying
-it, RLS rejects a wrong value, and the trigger forbids changing it later:
-
-```ts
-await ctx.db.insert('<entities>', { ...args, tenant: ctx.tenant })
-```
-
-## Role-level security — with or without tenancy
-
-`security.rules` receives the full auth bundle and returns convex-helpers
-`Rules`. It works standalone (no tenancy configured) or AND-composed with
-tenant isolation (`composeRules`) — a row must pass **every** rule set that
-defines the operation. Use it for role-gated writes, ownership-gated reads,
-or state-machine write locks:
-
-```ts
-// rules-only, single-org app: no tenancy anywhere
-security: {
-  rules: (bundle) => ({
-    '<entities>': { modify: async () => bundle.role !== '<readonly-role>' },
-  }),
-}
-```
-
-```ts
-rules: (bundle) => ({
-	'<entities>': {
-		modify: async (_ctx, doc) => bundle.role === 'admin' || doc.ownerId === bundle.actor.userId,
-	},
-	'<evidence>': { modify: async () => false }, // frozen via RLS as well as trigger
-})
-```
-
-## Client-supplied ids
-
-RLS makes foreign rows invisible to reads, but any id a client sends should
-still be re-verified — and without disclosing existence:
-
-```ts
-import { requireTenantReference } from 'cvx-kit/tenancy'
-
-const row = await requireTenantReference(ctx.tenant, () => ctx.db.get(args.id))
-// missing row and foreign row fail identically: REFERENCE_NOT_FOUND
-```
-
-`assertTenantOwned(tenant, doc)` is the internal-path variant
-(CROSS_TENANT_REFERENCE, for rows you already loaded on trusted paths).
-
-## Footguns
-
-1. **Actions have no db** — an action passing work to internal functions must
-   pass `ctx.tenant` (server-derived) as data; internal functions must never
-   accept a caller-chosen tenant on a public path.
-2. **Provider ids are global** (memberships, invitations in WorkOS-style
-   providers): org-scoped mutations against the provider must re-check the
-   id belongs to the active org, or you ship a cross-tenant IDOR.
-3. **Tables outside the registry get none of this.** Keep the global-table
-   list short and named; every one is a per-handler-discipline zone.
-4. **`t.run(...)` in convex-test bypasses RLS and triggers** — same rule as
-   always: seeding only.
-5. **Return "not found", never "forbidden"** for cross-tenant references —
-   existence is also tenant data.
-
-## Module maps
-
-`createModule` (from `cvx-kit/zod-table`) merges per-module table maps into
-the schema and rejects a table declared by two modules:
-
-```ts
-// convex/domain/table.ts
-export const domainTables = createModule(<moduleA>Tables, <moduleB>Tables, <moduleC>Tables)
-// convex/schema.ts
-export default defineSchema(domainTables)
-```

package/docs/triggers.md

@@ -1,77 +0,0 @@
-# `cvx-kit/triggers` — one application-wide mutation interceptor registry
-
-A single `Triggers` registry (from convex-helpers) is created once per app and
-handed to `createAuthFunctions`. From then on, every `authMutation`,
-`roleMutation`, and `systemMutation` runs its writes through
-`triggers.wrapDB(ctx)` — trigger enforcement is **structural, not a
-convention**. A handler cannot skip a trigger because it never sees an
-unwrapped `ctx.db`.
-
-## Setup
-
-```ts
-// convex/triggers.ts — the single registry
-import { appendOnly, createTriggers, noDelete, timestamps } from 'cvx-kit/triggers'
-import type { DataModel } from './_generated/dataModel'
-
-export const triggers = createTriggers<DataModel>()
-
-// Server-owned lifecycle timestamps (see zod-table.md)
-timestamps(triggers, 'documents', 'projects', 'members')
-
-// Evidence tables: inserts only — updates/deletes throw and roll back
-appendOnly(triggers, 'votes', 'history')
-
-// Soft-delete discipline: hard deletes throw
-noDelete(triggers, 'documents')
-
-// Domain triggers register on the same instance
-triggers.register('documents', async (ctx, change) => {
-	if (change.operation === 'insert') {
-		/* denormalize, validate, cascade */
-	}
-})
-```
-
-```ts
-// convex/functions.ts
-createAuthFunctions<DataModel>({ ..., triggers })
-```
-
-## The built-in helpers
-
-- **`timestamps(triggers, ...tables)`** — maintains zod-table's opinionated
-  fields: sets `createdAt` + `updatedAt` on insert, moves `updatedAt` on every
-  update. `archivedAt` stays under application control. Contains its own
-  recursion guard (a write that already moved `updatedAt` — including the
-  trigger's own patch — is left alone). Register once per table.
-- **`appendOnly(triggers, ...tables)`** — inserts pass; any update or delete
-  throws, which **rolls back the whole transaction**. The pattern for
-  votes/history/audit-style evidence tables.
-- **`noDelete(triggers, ...tables)`** — forbids hard deletes only; updates
-  pass. Pair with `archivedAt` for soft deletion.
-- **`tenantOwnership(triggers, ...tables)`** — the tenancy post-image
-  invariant: inserts must carry a non-empty `tenant`, updates may never
-  reassign it. Register for every table in the tenancy registry (row-level
-  security checks the pre-image only — this closes that hole). See
-  `tenancy.md`.
-
-`Triggers`, `Change`, and `Trigger` are re-exported for custom registrations.
-
-## Footguns
-
-1. **Anything outside the kit constructors bypasses every trigger.** Raw
-   `mutation`/`internalMutation` from `_generated/server`, and `ctx.db` inside
-   `convex-test`'s `t.run(...)`, are unwrapped. Never build a mutation outside
-   your `functions.ts`, and expect test-side `t.run` writes to be trigger-free
-   (useful for seeding, dangerous for assertions about trigger behavior).
-2. **Wrapper spread order matters** if you compose ctx manually:
-   `{ ...wrapDB(ctx), ...otherStuff }` — `wrapDB` returns a full ctx, so
-   spreading it _after_ anything that carries `db` restores the raw database.
-   The kit's constructors already order this correctly
-   (`{ ...wrapDB(ctx), include, ...authBundle }`).
-3. **A throwing trigger aborts the transaction.** That is the point for
-   `appendOnly`/`noDelete`, but remember it when writing custom triggers —
-   validation triggers should throw; best-effort denormalization should not.
-4. **Triggers run per write, in registration order.** Keep them small; heavy
-   work belongs in a scheduled function, not in a trigger.