You MUST define all tables in convex/schema.ts with defineSchema / defineTable.
System Fields: _id (v.id(tableName)) and _creationTime (v.number()) are added automatically.
You MUST use v.* validators for every field; SHOULD avoid v.any() unless necessary.
Index naming: include all fields in the name, e.g., "by_field1_and_field2".
Index rules:
- You MUST use .index(name, [fields...]).
- Field order matters; range expressions MUST follow index order.
- Limits: 16 fields per index, 32 indexes per table.

You MUST use new function syntax with args, returns, and handler.
You MUST always validate args and returns (HTTP actions excluded).
Use query for reads, mutation for writes, and action for external/long-running.
Actions MUST NOT access ctx.db; You MUST use ctx.runQuery / ctx.runMutation.
Circular Dependencies: When calling a function in the same file via ctx.run*, You MUST add explicit return type annotations to the receiver variable.

You MUST provide the explicit table name as the first argument to ctx.db.get, ctx.db.patch, ctx.db.replace, and ctx.db.delete.
Replacement: Use ctx.db.replace for full document replacement (throws if missing).
Patching: Use ctx.db.patch for shallow merge updates (throws if missing).
Deletion: Convex queries do NOT support .delete(). You MUST .collect() results and iterate to call ctx.db.delete(id).
Unique: Use .unique() for single document results; it MUST throw if multiple documents match.
You MUST NOT use filter in production queries; use indexes and .withIndex.

You MUST use as const for string literals in discriminated unions.
You MUST define arrays as const array: Array<T> = [...] and records as const record: Record<K, V> = {...}.
You MUST prefer Id<"table"> over string for all document identifiers.

You SHOULD prefer .withIndex over .filter on large tables.
If using .withIndex without a range, You MUST pair it with take, first, unique, or paginate.
Search limits: collect() throws if >1024 docs; You SHOULD use take(n), paginate(), or for await iteration for large sets.
Async iteration: Use for await (const row of query) instead of .collect() for streaming large result sets.

You MUST use paginationOptsValidator in args.
.paginate() returns { page, isDone, continueCursor }.
Pages are reactive; size MAY change.
You SHOULD avoid strict returns validators for the full .paginate() result object; validate page or use v.any().

You MUST enforce auth per function; check identity via ctx.auth helpers.
You MUST NOT expose sensitive logic in public functions; MUST use internal ones.

convex-core