cvx-kit 0.1.15 → 0.1.17

package/docs/llms.md

@@ -1,324 +0,0 @@
-# cvx-kit — condensed reference for LLMs and coding agents
-
-> Paste this file (installed at `node_modules/cvx-kit/docs/`) into an agent's
-> context when it works on a cvx-kit application. Detailed docs:
-> `architecture.md`, `conventions.md`, `zod-table.md`, `querying.md`, `auth.md`,
-> `commands.md`, `effect.md`, `domain-operations.md`, `triggers.md`, `approvals.md`, `maintainability.md`,
-> `migration.md` (same directory).
-> Structure, file anatomy, and naming rules → `conventions.md` is
-> authoritative. Restructuring an existing raw project → `migration.md`.
-> Upgrading from 0.0.x → `upgrading.md`. New 0.1.0 helpers: `crud.md`,
-> `webhooks.md`, `agent-tools.md`; stream/relationship pagination in `querying.md`,
-> table DTO and pagination helpers in `zod-table.md`.
-> Consumer lint configuration and coverage → `oxlint.md`. The optional
-> `cvx-kit/oxlint` plugin checks the statically detectable conventions;
-> behavioral guarantees still need architecture and runtime tests.
-
-> **Placeholders.** Names like `documents`, `users`, `history`, `title`,
-> `ownerId`, and `documentPublish` in the examples below are illustrative
-> only — replace them with the application's own entities and fields. No
-> specific table, entity, field, or workflow is required by the kit. Names in
-> `<angle brackets>` are always placeholders.
-
-cvx-kit is a reusable Convex application kit: zod table boundaries, auth-aware
-function constructors, a trigger registry, an audited command protocol
-(Foundation component), and a declarative approvals component. Peer deps:
-`convex ^1.46.0`, `zod ^4.5.4`; command implementations also install
-`effect >=4.0.1 <5` and import `cvx-kit/effect`.
-
-**Command API selection:** use `createEffectFoundation` and declare handlers
-inside `command({...})`. The older `Foundation.Command` Promise facade is
-deprecated. Its compatibility examples live in `commands-legacy.md`; do not
-copy that API into new implementations.
-
-## Non-negotiable rules
-
-1. **One `zodTable` per entity**, in `domain/<entity>/schema.ts`. Never write
-   `defineTable` inline or a second zod object for the same entity.
-2. **Raw `query`/`mutation`/`action`/`internal*` builders appear only in
-   `convex/functions.ts`** (the `createAuthFunctions` call). All other
-   functions use `authQuery/authMutation/authAction`, `roleQuery/...`,
-   `adminQuery/...` (public) or `systemQuery/systemMutation/systemAction` (internal),
-   built once with `createEffectAuthFunctions(config, policies)` from `cvx-kit/effect`
-   for shared Effect handles, or individually wrapped with `effectZodApiBuilder`.
-   This is what guarantees auth, triggers, and bounded reads.
-3. **Every public query returns DTOs** via `<table>.toPublicDto(row)` or the
-   querying engine. For IDs use `toPublicDto(row, true)` with `dto(true)`; for
-   computed fields use matching `extend` schemas and explicit `values`.
-   `publicDto` remains the default schema. Never manually append IDs to a DTO.
-4. **Every read is bounded**: `ctx.include(ctx.db.query('t')).matching(...)
-   .execute(limit)` with `1 ≤ limit ≤ 100`. `.resolve()` falls back to a full
-   table scan — avoid it. Alternatively use the independent querying engine
-   with table/registry `paginationOpts(selection)` and matching `pageDto`.
-   Declare relationships in root `relations.ts`, configure `createQueryEngine`
-   in root `querying.ts`, and paginate inside authenticated domain Query handlers.
-   Apply eligibility before limits; many relationships return bounded pages.
-   `order` reverses native index order; `.when(value, index)` selects an index
-   without binding fields. Unknown contexts fail closed and budget exhaustion
-   throws. See `querying.md` and the DTO/pagination rules in `oxlint.md`.
-5. **State changes are Effect commands**: declare
-   `Command({ context, operations: ({ command }) => ({ ... }), defaults })`.
-   Each `command({ input, result, classification, handler, audit })` owns its
-   handler; handlers receive `(input, context)`. Execute with
-   `commands.exec(operation, input, host)` and return the lazy Effect through a
-   shared API builder. Never pass a handler to `exec` or run a nested
-   `Effect.runPromise`. Permission uses the injected `checkPermission(host, ...)`;
-   guards receive `(context, input)`. Per-operation middleware is one callback,
-   `next()` returns an Effect, and `next({ context })` enriches downstream ctx.
-   Order: input → context → permission → prepare/replay → middleware → default
-   guard → operation guard → handler → result parse → aggregates/audit → completion.
-   Audit writes stay in the mutation transaction. Failures must escape the
-   mutation for rollback; replay skips middleware, guards, handler, and audit.
-6. **Never write timestamps by hand.** `createdAt`/`updatedAt` are maintained
-   by the `timestamps` trigger; `archivedAt` is the app-controlled soft-delete
-   marker.
-7. **Vocabularies are named readonly tuples in `constants.ts`** —
-   `z.enum([...])` with an inline literal is banned in kit-style codebases.
-8. **Components are consumed only through their client facades**
-   (`Foundation`, `Approvals`) — no deep imports, no touching component
-   tables, no reaching private children (`components.approvals.workflow`).
-9. **Operation names are `domain.verb` lowercase-dotted; error codes are
-   UPPER_SNAKE** — otherwise observability silently drops the events.
-10. **Row-level security is configured, not hand-rolled**: the optional
-    `security` config on `createAuthFunctions` takes role-level `rules`
-    (works standalone) and/or `tenancy` (a table registry; adds
-    `ctx.tenant`, deny-default isolation, and pairs with `tenantTable` +
-    `tenantOwnership`). Multi-tenant apps stamp inserts with
-    `tenant: ctx.tenant` and re-verify client ids with
-    `requireTenantReference`. See `tenancy.md`.
-
-## Exports map
-
-| Import                          | Provides                                                                                                                                                                                                |
-| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cvx-kit`                       | Non-Effect helpers and component clients; import the optional Effect facade explicitly from `cvx-kit/effect`.                                                                                           |
-| `cvx-kit/zod-table`             | `zodTable`, `tenantTable`, `createModule`, `paginated`, `zodVariantTable`, `jsonSafeZid`, `TIMESTAMP_FIELDS`                                                                                            |
-| `cvx-kit/effect`                | Recommended command/query API: `createEffectFoundation`, `createEffectAuthFunctions`, `effectApiBuilder`, `effectZodApiBuilder`, `createEffectCrud`, idempotency/workflow adapters and operation tools. |
-| `cvx-kit/auth`                  | `createAuthFunctions` (incl. optional `security` RLS config), `createInclude`, `defaultRoleMap`                                                                                                         |
-| `cvx-kit/tenancy`               | `createTenantRules`, `composeRules`, `requireTenantReference`, `assertTenantOwned`, `TENANT_FIELD`                                                                                                      |
-| `cvx-kit/crud`                  | Compatibility CRUD factory using the deprecated Promise command facade; use `createEffectCrud` from `cvx-kit/effect` for new domains.                                                                   |
-| `cvx-kit/state-machine`         | `createStateMachine` — typed transitions from constants tuples; `assert` drops into command guards                                                                                                      |
-| `cvx-kit/middleware`            | `rateLimit` — packaged middleware over an injected rate-limiter instance; keyed by `ctx.tenant`, missing key = config error                                                                             |
-| `cvx-kit/webhooks`              | `createWebhookBoundary`, `recordWebhookEvent`, `webhookEventsTable` — raw-body verify, natural-key dedup in the mutation                                                                                |
-| `cvx-kit/agent-tools`           | `createAgentTools` — tool records from table masks; mutation handlers route through command executors                                                                                                   |
-| `cvx-kit/triggers`              | `createTriggers`, `timestamps`, `appendOnly`, `noDelete`, `tenantOwnership`, `Triggers`                                                                                                                 |
-| `cvx-kit/errors`                | `KitError`, `defaultErrors`, `ErrorFactory`                                                                                                                                                             |
-| `cvx-kit/components/foundation` | Component client and types; `Foundation.Command` is deprecated. The component and other capabilities remain available. New command registries use `cvx-kit/effect`.                                     |
-| `cvx-kit/components/approvals`  | `Approvals` client; default export = component config for `app.use`                                                                                                                                     |
-| `cvx-kit/test`                  | `registerFoundation(t)`, `registerApprovals(t)` for convex-test                                                                                                                                         |
-
-## Minimal app wiring (the five root files)
-
-```ts
-// convex/convex.config.ts
-import { defineApp } from 'convex/server'
-import foundation from 'cvx-kit/components/foundation/convex.config'
-import approvals from 'cvx-kit/components/approvals/convex.config'
-const app = defineApp()
-app.use(foundation)
-app.use(approvals)
-export default app
-
-// convex/triggers.ts
-import { createTriggers, timestamps, appendOnly } from 'cvx-kit/triggers'
-export const triggers = createTriggers<DataModel>()
-timestamps(triggers, 'documents')
-appendOnly(triggers, 'history')
-
-// convex/functions.ts
-export const {
-	authQuery,
-	authMutation: baseAuthMutation,
-	authAction,
-	adminQuery,
-	adminMutation,
-	adminAction,
-	roleQuery,
-	roleMutation,
-	roleAction,
-	systemQuery,
-	systemMutation,
-	systemAction,
-	include,
-} = createAuthFunctions<DataModel>({
-	query,
-	mutation,
-	action,
-	internalQuery,
-	internalMutation,
-	internalAction, // from ./_generated/server
-	getAuthUser: (ctx) => authKit.getAuthUser(ctx),
-	mapRole: defaultRoleMap, // 'member'→'writer'; reader|writer|admin pass
-	adminRoles: ['admin'],
-	triggers,
-	verifyMembership: async ({ userId, organizationId }) => {
-		/* live check; actions only */
-	},
-	resolveOrganization: async ({ ctx, identity, user }) => {
-		/* org+role from app tables; overrides claims; null/throw ⇒ FORBIDDEN */
-	},
-})
-
-// convex/functions.ts — wrap configured auth constructors once, after auth/RLS/triggers
-// Import Context from effect and effectZodApiBuilder from cvx-kit/effect.
-// Place this after the registry declaration or import the registry from its module.
-export const authMutation = effectZodApiBuilder(baseAuthMutation, {
-	context: (ctx) => ({ commands: commands.withContext(ctx) }),
-})
-
-// convex/foundation.ts
-// Import createEffectFoundation from cvx-kit/effect.
-import type { MutationCtx } from './_generated/server'
-export type CommandHost = MutationCtx & { actor: { userId: string } }
-export const { Command, Query, observability } = createEffectFoundation({
-	observability: {
-		enabled: () => process.env.OBS === 'true',
-		classifyError, // → { outcome: 'denied'|'failed', errorCode }
-	},
-	writeAudit: (ctx: CommandHost, entry) => writeAuditEntry(ctx, entry),
-})
-
-// convex/approvals.ts
-export const approvals = new Approvals(components.approvals)
-```
-
-## Entity pattern
-
-```ts
-// domain/documents/schema.ts
-export const documents = zodTable(
-	'documents',
-	(id) => ({
-		title: z.string(),
-		ownerId: id('users'),
-		secretNote: z.string(),
-	}),
-	{
-		commandFields: ['title'], // what a command may say
-		publicFields: ['title', 'ownerId'], // the DTO allowlist
-	},
-)
-
-// convex/schema.ts (via domain/table.ts)
-defineSchema({ documents: documents.table.index('by_owner', ['ownerId']) })
-
-// domain/documents/commands.ts
-export const renameInput = documents.commandInput.extend({ id: zid('documents') })
-export const renameResult = z.object({ ok: z.literal(true) }).strict()
-export const commands = Command({
-	context: (host: CommandHost) => host,
-	operations: ({ command }) => ({
-		'documents.rename': command({
-			input: renameInput,
-			result: renameResult,
-			classification: 'business',
-			handler: async (input, ctx) => {
-				await ctx.db.patch(input.id, { title: input.title })
-				return { ok: true as const }
-			},
-			audit: ({ command }, ctx) => ({
-				operation: 'documents.rename',
-				actorId: ctx.actor.userId,
-				aggregate: { type: 'document', id: command.id },
-			}),
-		}),
-	}),
-})
-
-// api/documents.ts — thin public adapter
-export const rename = authMutation({
-	args: renameInput,
-	returns: renameResult,
-	handler: (ctx, input) => ctx.commands.exec('documents.rename', input),
-})
-export const list = authQuery({
-	args: { limit: z.number() },
-	returns: z.array(documents.publicDto),
-	handler: (ctx, { limit }) =>
-		ctx
-			.include(ctx.db.query('documents'))
-			.matching('by_owner', (ix) => ix.eq('ownerId', ctx.actor.userId))
-			.execute(limit, (rows) => rows.map(documents.toPublicDto)),
-})
-```
-
-## Auth ctx contents
-
-Authenticated handlers receive frozen `ctx.identity` (JWT), `ctx.user.id`,
-`ctx.org = { organizationId, role }`, `ctx.role`, `ctx.actor = { userId,
-organizationId, role }`, and `ctx.include`. Queries/mutations trust the JWT;
-**actions live-verify membership and fail closed**. Use `ctx.actor` as the
-canonical actor for audits/approvals.
-
-## Approvals in one block
-
-```ts
-export const publishApproval = approvals.define({
-	name: 'documentPublish',
-	steps: [
-		approvals.decision('managerDecision', {
-			decisions: ['approved', 'rejected'],
-			quorum: { kind: 'count', approvals: 1 },
-			makerChecker: true,
-			expiresAfterMs: 604_800_000,
-		}),
-		approvals.branch('applyDecision', { approvedStepKey: 'publish', rejectedStepKey: 'notify' }),
-		approvals.mutation('publish', {
-			handler: internal.domain.documents.approval_functions.applyDecision,
-		}),
-		approvals.notify('notify', {
-			handler: internal.domain.documents.approval_functions.notifyRejected,
-		}),
-	],
-})
-// start(ctx, { scopeRef, resourceType, resourceRef, requester: ctx.actor, metadata? })
-// decide(ctx, { runId, decision, reason? }, ctx.actor) · status/evidence/list/cancel/restart
-```
-
-Callback handlers are `systemMutation`/`systemAction`, receive opaque strings,
-and must `normalizeId` + re-check `resourceType` + verify the resource still
-points at `runId`.
-
-## Footguns (top 8)
-
-1. `t.run(ctx => ctx.db...)` in convex-test and raw builders bypass ALL
-   triggers — seeding only.
-2. `executeResultBoundary` returns a typed failure **only when the
-   transaction has no effects yet**; after any write/schedule it rethrows for
-   rollback. Handled-vs-thrown is decided by transaction state.
-3. Observability drops events on identifier-regex mismatch — see rule 9.
-4. Mis-declared `serverFields` silently make server-owned fields
-   client-writable; masks are the security boundary.
-5. `include(...).resolve()` silently falls back to `fullTableScan()`.
-6. Command audit actors come from trusted host context, never client input.
-   Commands with writes must run through mutation builders with wrapped `ctx.db`.
-7. Changing approval steps without bumping `compatibilityKey` lets old runs
-   be driven by an incompatible shape.
-8. When composing ctx manually, spread `wrapDB(ctx)` first — later spreads
-   carrying `db` restore the unwrapped database.
-
-Optional request context can be added through the existing Effect API adapter's
-`context` callback. Bind selected registries with `commands.withContext(value)`
-and consume `ctx.commands.exec(name, input)` through the application's existing
-function helper names. Keep dependencies local to each feature; explicit execution
-and input-only command handlers remain supported. See [optional context injection](./command-context.md).
-
-## Shared auth and Effect context
-
-Configure `createEffectAuthFunctions` once in `convex/functions.ts` using a typed
-`AuthFunctionsConfig<DataModel, Role>` and inferred factory generics. Supply six
-explicit policies: `query`, `mutation`, `action`, `systemQuery`, `systemMutation`,
-and `systemAction`; use `{}` for no additions. Each supports `services`,
-`context`, and `mapError`. All auth/role/admin constructors share the policy
-for their kind. Services and context initialize only after successful auth and
-role checks, using the secured DB and refreshed live action membership.
-
-Bind query registries only in queries. Mutations can bind queries and commands
-with their secured triggered writer. Actions have no DB; bind action-compatible
-registries or delegate with `runMutation`/`runQuery`. Each registered mutation
-has its own transaction and JWT auth; an action is not one transaction. Configure
-internal system authority separately, without fabricated actors or inherited
-public handles. Return plain records with handles under named keys; native/auth
-key collisions are rejected, including inherited keys at runtime. Keep bound
-handles request-local, return lazy Effects, and let failures escape mutations
-for rollback. See `auth.md` for a packed-compiled shared factory example.

package/docs/maintainability.md

@@ -1,124 +0,0 @@
-# Maintaining a Convex application built on cvx-kit
-
-Practices that keep a cvx-kit backend maintainable over years, taken from the
-origin application. The theme throughout: make every rule either _structural_
-(the code can't be written any other way) or _executable_ (a test fails when
-it's violated). Conventions that live only in documentation decay.
-
-## Schema and indexes
-
-- `convex/schema.ts` stays at ~4 lines: `defineSchema(domainTables)`.
-  Per-domain `table.ts` files attach indexes to `<zodTable>.table` and
-  `domain/table.ts` merges the maps. Shapes (zod) and topology (indexes) are
-  deliberately separate files.
-- **Index naming**: `by_<field>_and_<field>...`, camelCase field names in
-  declaration order, nested paths flattened with `_`
-  (`by_assignedToUserId_and_state_status` for `['assignedToUserId',
-'state.status']`). A reader should reconstruct the index definition from its
-  name.
-- Every read goes through `ctx.include(...)` with an explicit limit ≤ 100.
-  If a query can't be served by an index, that's a schema problem, not a
-  reason to `fullTableScan`.
-
-## Schema evolution without downtime
-
-Convex validates the whole table against the schema on push, so evolution is
-additive:
-
-1. **New fields arrive `.optional()`** with a comment explaining the epoch:
-   `// Optional only for documents created before priority was frozen.`
-2. Deploy code that writes the new field on every new write and tolerates its
-   absence on reads.
-3. Backfill if needed (a `systemMutation` batch or `@convex-dev/migrations`),
-   then — and only then — consider tightening the schema.
-4. Never rename in place: add the new field, dual-write, backfill, drop the
-   old one release(s) later.
-
-zod-table makes step 1 cheap: change the shape once and every boundary mask
-updates together, with `tsc` pointing at every consumer that must adapt.
-
-## Function hygiene
-
-- Raw `query`/`mutation`/`action` builders appear **only** in `functions.ts`.
-  Everything public is `auth*`/`role*`/`admin*`; everything
-  internal/scheduled is `system*`. This is what makes triggers, auth, and
-  bounded reads impossible to forget.
-- Public functions in `api/` are thin: parse args (zod-table masks), call the
-  domain executor with `ctx.actor`, project through `toPublicDto`. Business
-  logic that lives in an adapter can't be reused by workflows or callbacks —
-  keep it in the domain.
-- Vocabularies (states, kinds, decisions) are single-owner readonly tuples in
-  `constants.ts`. Grep for the tuple name to find every consumer.
-
-## Audit and observability as maintenance tools
-
-- Every state change is a command with a mandatory classification and audit
-  derivation — so "what happened to this record" is a query over the audit
-  log, not archaeology. Keep operation names stable (`domain.verb`); they are
-  your telemetry and audit vocabulary.
-- Observability is payload-free by construction — you can leave it on in
-  production and grep durable one-line JSON events
-  (`event: 'command.execution'`) without PII review.
-- Set retention deliberately: audit entries carry the classification as their
-  retention category; the approvals component ships `cleanupAudit` for its own
-  trail.
-
-## Testing strategy
-
-Three test layers, all in-memory via `convex-test` on `edge-runtime`:
-
-1. **Behavioral tests** — drive functions through the real constructors
-   (`t.withIdentity(...)`), assert DTO shapes and trigger effects. Remember:
-   `t.run(ctx => ctx.db...)` bypasses triggers — use it for seeding, not for
-   asserting write behavior.
-2. **Architecture tests** — glob the source and assert the conventions
-   (no inline tables/enums, no deep imports, no sibling-domain imports, one
-   `app.use` per component, no raw builders outside `functions.ts`). Prove
-   each rule against a synthetic violating fixture first.
-3. **Boundary/copyability tests** — components contain no host imports and no
-   vendor/env references; optionally `cp -r` the component to a tmpdir and
-   run `tsc` to prove copy-portability.
-
-Consumers register the kit's components on their test instance:
-
-```ts
-import { convexTest } from 'convex-test'
-import { registerApprovals, registerFoundation } from 'cvx-kit/test'
-
-const t = convexTest(schema, modules)
-registerFoundation(t)
-registerApprovals(t)
-```
-
-(`cvx-kit/test` ships as source and needs a vitest-compatible runner —
-`import.meta.glob`.) Nested components used by approvals register their own
-test modules the same way (`@convex-dev/workflow/test`,
-`convex-audit-log/test`). Stub required env vars (declared on
-`defineApp({ env })`) in test setup.
-
-## Operational habits
-
-- **Env flags over redeploys**: observability is toggled by an env var read
-  at call time (`enabled: () => env.OBS === 'true'`).
-- **Fail closed**: membership verification errors reject; unknown roles
-  reject; unreadable transaction metrics rethrow. Preserve this bias in app
-  code.
-- **Soft deletes** (`archivedAt` + `noDelete`) for anything a human might ask
-  about later; `appendOnly` for evidence tables. Hard deletes are a data-loss
-  bug you opt into per table.
-- **Component upgrades**: components own their tables; upgrade them like
-  services — read the component's migration notes, bump, run codegen, run the
-  suite. Never write to a component's tables from the host.
-
-## Checklist for a new entity
-
-1. `domain/<entity>/schema.ts` — `zodTable` with the three masks thought
-   through (`serverFields`, `commandFields`, `publicFields`).
-2. `domain/<entity>/table.ts` — indexes, named `by_...`.
-3. Register in `domain/table.ts`; add `timestamps(triggers, '<table>')` and
-   any `appendOnly`/`noDelete` discipline.
-4. `constants.ts` — vocabularies as readonly tuples.
-5. `commands.ts` — operation registry (`domain.verb`, classification, audit)
-   - executors.
-6. `api/<entity>.ts` — thin `auth*` adapters, DTO projection.
-7. Tests: behavior + add the entity to the architecture globs.