cvx-kit 0.0.1 → 0.0.2

package/docs/llms.md

@@ -0,0 +1,194 @@
+# 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`, `auth.md`,
+> `commands.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`.
+
+> **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.43`, `zod ^4`.
+
+## 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 `systemMutation/systemAction` (internal).
+   This is what guarantees auth, triggers, and bounded reads.
+3. **Every public query returns DTOs** via `<table>.toPublicDto(row)` —
+   runtime redaction, not just types.
+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.
+5. **State changes are commands**: an operations registry with mandatory
+   `classification` and `audit()` per operation, executed via
+   `commands.exec({ operation, handler })`. Audit writes happen in the same
+   transaction.
+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.
+
+## Exports map
+
+| Import | Provides |
+|---|---|
+| `cvx-kit` | everything below re-exported (except components' defaults) |
+| `cvx-kit/zod-table` | `zodTable`, `zodVariantTable`, `jsonSafeZid`, `TIMESTAMP_FIELDS` |
+| `cvx-kit/auth` | `createAuthFunctions`, `createInclude`, `defaultRoleMap` |
+| `cvx-kit/triggers` | `createTriggers`, `timestamps`, `appendOnly`, `noDelete`, `Triggers` |
+| `cvx-kit/errors` | `KitError`, `defaultErrors`, `ErrorFactory` |
+| `cvx-kit/components/foundation` | `Foundation`, `executeResultBoundary`, `projectResult`, `Observability`; default export = component config for `app.use` |
+| `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'
+import approvals from 'cvx-kit/components/approvals'
+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, authAction, adminQuery, adminMutation,
+  adminAction, roleQuery, roleMutation, roleAction, systemMutation,
+  systemAction, include } = createAuthFunctions<DataModel>({
+  query, mutation, action, 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 */ },
+})
+
+// convex/foundation.ts
+export const { Command, Query, observability } = new Foundation(
+  components.foundation,
+  { observability: {
+      enabled: () => process.env.OBS === 'true',
+      classifyError,                                  // → { outcome: 'denied'|'failed', errorCode }
+      writeAudit: (ctx, 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
+const operations = {
+  'documents.rename': Command.operation({
+    command: documents.commandInput.extend({ id: zid('documents'), actorId: z.string() }),
+    result: z.object({ ok: z.literal(true) }).strict(),
+    classification: 'business',
+    audit: ({ command }) => ({ operation: 'documents.rename', actorId: command.actorId,
+      aggregate: { type: 'document', id: command.id } }),
+  }),
+} as const
+const commands = new Command<MutationCtx, typeof operations>(operations)
+export const executeRename = commands.exec({ operation: 'documents.rename',
+  handler: async (ctx, cmd) => { await ctx.db.patch(cmd.id, { title: cmd.title }); return { ok: true } } })
+
+// api/documents.ts — thin public adapter
+export const rename = authMutation({
+  args: documents.commandInput.extend({ id: zid('documents') }),
+  returns: z.object({ ok: z.literal(true) }).strict(),
+  handler: (ctx, args) => executeRename(ctx, { ...args, actorId: ctx.actor.userId }),
+})
+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. Audit callback ctx is untyped (`never`) — commands must run in mutations;
+   wiring a query ctx fails at runtime.
+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.

package/docs/maintainability.md

@@ -0,0 +1,124 @@
+# 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.

package/docs/migration.md

@@ -0,0 +1,351 @@
+# Migrating an existing Convex project to the cvx-kit architecture
+
+This guide takes a "raw" Convex project — the typical shape where every file at
+the root of `convex/` exports public queries and mutations, tables are defined
+inline in `schema.ts`, and validators are `v.*` objects repeated per function —
+and restructures it into the cvx-kit architecture.
+
+This is an **opinionated infrastructure**. The rules below are not
+suggestions; they are the contract. Where the kit makes something structural
+(auth, triggers, bounded reads, mandatory audit), the migration's job is to
+remove every code path that circumvents the structure. Names in `<angle
+brackets>` are placeholders for your own vocabulary — no specific entity,
+table, field, or workflow is mandated, only the roles and rules.
+
+Migrate incrementally: each step leaves the app deployable, and old and new
+shapes can coexist while you move entity by entity.
+
+---
+
+## 1. The target structure — complete
+
+```
+convex/
+  convex.config.ts            # component mounting. Nothing else.
+  schema.ts                   # defineSchema(domainTables). Nothing else.
+  functions.ts                # the single createAuthFunctions(...) call
+  triggers.ts                 # the single trigger registry + helper registrations
+  foundation.ts               # the single new Foundation(...) facade
+  <component>.ts              # one facade per mounted component (audit.ts, approvals.ts, pool.ts, workflows.ts, ...)
+  auth.ts                     # identity-provider client wiring
+  auth.config.ts              # Convex auth providers config
+  http.ts                     # HTTP router (webhook endpoints delegate to domains)
+  crons.ts                    # cron declarations only; targets are internal domain functions
+
+  api/                        # ═══ THE ONLY PUBLIC SURFACE ═══
+    <entity>.ts               # thin adapters: auth* constructors → domain executors → DTOs
+
+  domain/                     # ═══ ALL BUSINESS LOGIC ═══
+    table.ts                  # merges per-entity table maps into domainTables
+    shared/                   # genuinely cross-entity code ONLY
+      schema.ts               #   cross-entity zod helpers (if any)
+      <provider>.ts           #   one configured vendor client per provider (sql, cache, email, ...)
+    <entity>/                 # one directory per entity/aggregate
+      schema.ts               #   the zodTable declaration — shapes and masks, nothing else
+      table.ts                #   index topology attached to <zodTable>.table
+      constants.ts            #   finite vocabularies: UPPER_SNAKE readonly tuples
+      commands.ts             #   operation registry + command executors
+      queries.ts              #   domain read logic
+      rules.ts                #   pure domain invariants/predicates (no ctx, no db)
+      shared.ts               #   helpers shared by multiple files of THIS entity
+      <workflow>.ts           #   approval/workflow definitions this entity owns
+      <workflow>_functions.ts #   internal callback targets (system* constructors)
+      actions.ts              #   external-side-effect logic (via shared provider clients)
+      __tests__/              #   behavioral tests for this entity
+
+  components/                 # only if the app authors its own portable components
+    <name>/                   # own convex.config.ts, schema.ts, _generated/, __tests__/
+
+  __tests__/                  # ═══ APP-WIDE GUARDRAILS ═══
+    setup.ts                  # env stubs for vars declared on defineApp({ env })
+    architecture.test.ts      # the executable conventions (see §6)
+    facades.test.ts           # each app.use exactly once; no private-child access
+```
+
+### The root rule
+
+**The root of `convex/` contains configuration and facades only.** Every root
+file is a *declaration point* — the single place one piece of infrastructure
+is configured — and none of them exports a public function or contains
+business logic. If a client can call it, it lives in `api/`. If it decides
+anything about the business, it lives in `domain/`. If `ls convex/*.ts` shows
+anything else, the migration is not done.
+
+### Hard prohibitions (grep-able, test-enforceable)
+
+These patterns must not exist anywhere after migration — each one is a hole in
+a structural guarantee:
+
+| Forbidden | Where it's allowed instead | What it breaks otherwise |
+|---|---|---|
+| `query(`, `mutation(`, `action(`, `internalMutation(`, `internalAction(` from `_generated/server` | `functions.ts` only | auth, triggers, bounded reads |
+| `defineTable(` | `domain/<entity>/table.ts` via `<zodTable>.table` | single source of truth per entity |
+| `defineSchema(` | root `schema.ts` only | schema assembly |
+| inline `z.enum([...])` / repeated literal unions | tuple in `constants.ts` | vocabulary ownership |
+| `.collect()` / unbounded reads in public paths | `ctx.include(...).execute(limit)` | read bounds |
+| `makeFunctionReference` | generated `internal` / `api` | refactoring safety |
+| deep imports of a component's internals | the component's client facade | component boundary |
+| sibling-domain imports (`domain/a` → `domain/b`) | `domain/shared/` or the public API | ownership |
+| `ctx.db.insert/patch/delete` on a mounted component's tables | the component's client methods | component persistence |
+| vendor SDK instantiation inside a domain | one shared client in `domain/shared/<provider>.ts` | connection discipline |
+| `new Date().toISOString()` / hand-written timestamp fields | the `timestamps` trigger | server-owned lifecycle |
+
+---
+
+## 2. Where each kind of existing code goes
+
+A raw project's root files usually mix several kinds of code. Pull them apart:
+
+| You have today | It becomes |
+|---|---|
+| `export const get/list = query({...})` at root | adapter in `api/<entity>.ts` + read logic in `domain/<entity>/queries.ts` |
+| `export const create/update = mutation({...})` at root | adapter in `api/<entity>.ts` + operation in `domain/<entity>/commands.ts` |
+| `internalMutation`/`internalAction` helpers | `system*` functions in `domain/<entity>/<purpose>_functions.ts` |
+| inline `defineTable({...})` in `schema.ts` | `zodTable` in `domain/<entity>/schema.ts` + indexes in `domain/<entity>/table.ts` |
+| `v.union(v.literal(...))` / inline `z.enum` repeated around | one `UPPER_SNAKE` tuple in `domain/<entity>/constants.ts` |
+| validation/business `if`-chains inside handlers | pure predicates in `domain/<entity>/rules.ts` |
+| shared grab-bag (`helpers.ts`, `utils.ts`, `lib.ts`) | split by owner into `domain/<entity>/shared.ts`; only genuinely cross-entity code into `domain/shared/` |
+| ad-hoc vendor clients (HTTP SDKs, caches, SQL) | one configured client per provider in `domain/shared/<provider>.ts` |
+| webhook handlers with logic in `http.ts` | route in `http.ts`, logic in `domain/<entity>/actions.ts` |
+| cron handlers with logic in `crons.ts` | declaration in `crons.ts`, target `system*` function in the domain |
+| audit/log/history tables mirroring component state | the component's own persistence via its facade |
+
+---
+
+## 3. Naming — the full convention set
+
+Naming is part of the architecture: several kit mechanisms key off it at
+runtime (observability drops non-conforming events), and the rest makes the
+codebase greppable.
+
+- **Directories**: `domain/<entity>/` uses the plural camelCase table name.
+  One entity, one directory — no `domain/misc/`.
+- **Tables**: plural camelCase (`<entities>`).
+- **Indexes**: `by_<field>` / `by_<field>_and_<field>`, fields in declaration
+  order, nested paths flattened with `_` (`by_ownerId_and_state_status` for
+  `['ownerId', 'state.status']`). A reader must be able to reconstruct the
+  index definition from its name.
+- **Command operations**: `<entity>.<verb>` lowercase dotted
+  (`invoices.approve`). Must match `/^[A-Za-z][A-Za-z0-9_.-]{0,159}$/` or
+  observability drops the events.
+- **Error codes**: `UPPER_SNAKE`, matching `/^[A-Z][A-Z0-9_]{0,95}$/`. Define
+  the full set once (one owner), not per callsite.
+- **Vocabulary tuples**: `UPPER_SNAKE_CASE` exported `as const`; derived type
+  `PascalCase` singular (`const <ENTITY>_STATES = [...] as const;
+  type <Entity>State = (typeof <ENTITY>_STATES)[number]`).
+- **Domain executors**: `execute<Verb><Entity>` (`executeApproveInvoice`) —
+  the grep-able seam between adapters and domain.
+- **Internal callback files**: `<purpose>_functions.ts` next to the
+  `<purpose>.ts` that references them.
+- **Public function names** are `api/<entity>:fn` — clients never reference a
+  root-level path.
+
+---
+
+## 4. Step-by-step migration
+
+### Step 0 — Inventory
+
+List every exported function and classify it: public read, public write,
+internal, cron target, HTTP handler. List every table, every index, every
+literal string union, every vendor client instantiation. This is the
+checklist; entities with the fewest dependencies migrate first.
+
+### Step 1 — Mount the kit, declare the root files
+
+Install `cvx-kit`, mount `foundation` (and `approvals` if needed) in
+`convex.config.ts`, run codegen. Create `functions.ts`, `triggers.ts`,
+`foundation.ts`, and one facade per mounted component. Declare required env
+vars on `defineApp({ env: { ... } })` so deploys fail fast, and stub them in
+`__tests__/setup.ts`. Nothing breaks: raw functions keep working alongside
+the new constructors.
+
+### Step 2 — Convert tables entity by entity
+
+For each table:
+
+1. `domain/<entity>/schema.ts`: a `zodTable` mirroring the current shape,
+   `v.*` converted to zod. Decide the three masks **deliberately** —
+   `serverFields` (server-assigned), `commandFields` (what a write request
+   may say), `publicFields` (what a client may see). This is where implicit
+   trust becomes explicit policy; a mis-declared mask is a security bug, so
+   review masks like auth code.
+2. `domain/<entity>/table.ts`: move the indexes, renamed to the convention.
+3. Register in `domain/table.ts`; shrink root `schema.ts` toward
+   `defineSchema(domainTables)`.
+4. The kit's timestamps are `.optional()`, so existing rows validate without
+   backfill. Register `timestamps(triggers, '<table>')`; new writes maintain
+   `createdAt`/`updatedAt`. Backfill later if needed. Existing hand-rolled
+   timestamp fields (e.g. ISO strings) stay in the shape for now — migrate
+   the data separately; never couple data migration to restructuring.
+5. Apply write discipline per table while you're here: `appendOnly` for
+   evidence tables (votes, history), `noDelete` + `archivedAt` for anything a
+   human might ask about later. Hard deletes are opt-in per table, not the
+   default.
+
+### Step 3 — Move vocabularies to `constants.ts`
+
+Every reusable finite vocabulary gets one owner: an exported tuple in the
+owning entity's `constants.ts`. Schemas, validators, filters, transition
+maps, and tests consume the tuple. Subsets and ordered presentations derive
+from the canonical tuple, typed against its value type so an invalid literal
+cannot compile. A file-local tuple is acceptable **only** for private
+implementation mechanics that can never appear in another schema, contract,
+persisted document, or UI state — and it is still `UPPER_SNAKE_CASE`.
+
+### Step 4 — Split public functions into adapter + domain logic
+
+For each public function at the root:
+
+1. **Extract the domain logic.** Reads → `domain/<entity>/queries.ts`.
+   Writes → an operation in the entity's command registry with
+   classification and audit derivation (see `commands.md`) — deciding *what
+   gets audited and as what* is a product decision; make it explicitly, not
+   as an afterthought. Pure conditions the handler checks
+   (state-transition legality, permission-beyond-role predicates) →
+   `rules.ts`, so they're unit-testable without a ctx.
+2. **Write the adapter** in `api/<entity>.ts` with `authQuery`/
+   `authMutation`/`role*`/`admin*`. Adapters do exactly four things: parse
+   args with the entity's boundary schemas, authorize via the constructor
+   choice, call the domain executor with `ctx.actor`, project through
+   `toPublicDto`. **Adapter budget: if it exceeds ~10 lines of glue or grows
+   a private helper, logic is leaking — move it into the domain.**
+3. **Retire the old path.** Public names change to `api/<entity>:fn`; update
+   client call sites per entity, or keep a temporary re-export file at the
+   old path and delete it in the final step.
+
+Anything "public-but-really-internal" (only called by your own scheduled
+functions or other backend code) must stop being public: convert to `system*`
+in the domain.
+
+### Step 5 — Convert internal functions and the wiring files
+
+- Replace raw `internalMutation`/`internalAction` with `systemMutation`/
+  `systemAction` from `functions.ts`, located in the owning domain's
+  `<purpose>_functions.ts`. Scheduled and callback writes now run under the
+  same trigger regime as user writes.
+- `crons.ts` becomes declarations only, targeting `internal.domain.<entity>.
+  <purpose>_functions.*`.
+- `http.ts` becomes routing only: verify the webhook signature, parse the
+  payload at the boundary, delegate to a domain action/function.
+
+### Step 6 — Bound the reads
+
+Replace `.collect()` and unbounded `.take(n)` in public paths with
+`ctx.include(...).execute(limit)` (limit ≤ 100). Where a query can't be
+served by an index, **add the index** — a scan is a schema problem, not a
+query-code problem. Paginated surfaces cross the boundary with the convex
+pagination validators bridged into zod (`convexToZod(paginationOptsValidator)`
+and a `paginationResultValidator` built from the row validator), not with
+hand-rolled cursor objects.
+
+### Step 7 — Enforce everything with tests
+
+Port the executable-architecture pattern. `__tests__/architecture.test.ts`
+globs all production sources and asserts the Hard Prohibitions table above;
+**each rule is proved against a synthetic violating fixture first** so a
+broken checker cannot silently pass. `facades.test.ts` asserts each
+`app.use(x)` appears exactly once and no file reaches a component's private
+children. From this point the migration cannot regress — and neither can
+future contributors or coding agents.
+
+---
+
+## 5. File conduct — how every source file is organized
+
+From the origin project's code conduct. Apply to new code and files being
+substantially changed; don't mechanically rewrite untouched files.
+
+**File order** — readable from public purpose to private implementation:
+
+1. Imports.
+2. Exported types, schemas, constants, and public functions — the API.
+3. File-local types and constants supporting the implementation.
+4. Private helpers, as **named function declarations**, at the bottom.
+
+```ts
+import { parseInput } from './schema'
+
+export async function createProjection(input: unknown) {
+  return buildProjection(parseInput(input))
+}
+
+function buildProjection(input: ProjectionInput) {
+  // implementation
+}
+```
+
+Never place private helper implementations above the exported API. Prefer
+`function` declarations over helper arrow-constants so helpers can live at
+the bottom.
+
+**Ownership.** Put behavior beside the entity that owns it. Consumers (api
+adapters, cron targets, workflow callbacks) stay thin: validate, authorize,
+call the owning operation, translate the result. A consumer accumulating
+entity rules or a pile of private helpers is logic asking to move into the
+domain.
+
+**No convenience re-exports.** Import a function from the file that owns it;
+never re-export to shorten a path. Barrel files (`index.ts` re-exporting a
+directory) are banned inside `convex/` — they blur ownership and create
+import cycles.
+
+**Components own their persistence.** Never mirror a mounted component's
+internal state (audit events, workflow steps, job results) into application
+tables unless the product domain independently requires a durable business
+record. Log through the facade; don't build a receipts table for it.
+
+**Comments state constraints, not narration.** The accepted pattern for
+schema evolution is a one-line epoch comment on an `.optional()` field
+explaining why it's optional. Comments that restate the next line are noise.
+
+---
+
+## 6. Documentation the migrated repo must carry
+
+An opinionated codebase documents its opinions, or they die at the first
+new contributor. Minimum set:
+
+- **`CODE_CONDUCT.md`** (or equivalent) — the repo's own conventions: file
+  order, ownership layout, vocabulary rules, naming. This guide's §3 and §5
+  are the starting template; adapt, don't link.
+- **`CONCEPTS.md`** — the domain glossary: every entity, state, and
+  vocabulary word with its business meaning. LLMs and new hires read this
+  first; keep entries one paragraph.
+- **`CLAUDE.md` / `AGENTS.md`** — thin pointers: the stack, the three
+  commands that matter (test, typecheck, deploy), and links to
+  `CODE_CONDUCT.md` + `node_modules/cvx-kit/src/docs/llms.md`. Agent files
+  that duplicate the conduct doc drift; keep them as an index.
+- **Architecture tests as documentation** — the test names in
+  `architecture.test.ts` are the enforceable summary of the conduct doc;
+  a rule that exists in prose but not in the suite is a request, not a rule.
+
+---
+
+## 7. Definition of done
+
+The migration is complete when every box checks:
+
+- [ ] `ls convex/*.ts` shows only configuration and facades (§1 table).
+- [ ] Every public function lives in `api/` and uses `auth*`/`role*`/`admin*`.
+- [ ] Every internal function uses `system*` and lives in its domain.
+- [ ] `functions.ts` is the only file importing `_generated/server` builders.
+- [ ] Every table is a `zodTable` with deliberately reviewed masks; indexes
+      named by convention; timestamps trigger registered.
+- [ ] Every vocabulary is a single-owner tuple in a `constants.ts`.
+- [ ] Every state change is a command operation with classification + audit.
+- [ ] Every public read is bounded (`include` + limit, or bridged pagination).
+- [ ] No entry in the Hard Prohibitions table greps positive.
+- [ ] `architecture.test.ts` + `facades.test.ts` exist, each rule fixture-proved.
+- [ ] `CODE_CONDUCT.md` and `CONCEPTS.md` exist; agent files point at them.
+- [ ] Transitional re-exports deleted; clients call `api/<entity>:fn` paths.
+
+## Migration order that works
+
+1. Root files + kit mounting (step 1) — zero behavioral change.
+2. The smallest, least-referenced entity end-to-end (steps 2–6) — shakes out
+   masks, role mapping, and conventions on a low-stakes surface.
+3. Architecture tests (step 7) — lock the rules in **before** the bulk.
+4. Remaining entities in dependency order, one PR each.
+5. Delete transitional re-exports and remaining root function files; run the
+   definition-of-done checklist.