cvx-kit 0.0.1 → 0.0.3

package/docs/commands.md

@@ -0,0 +1,229 @@
+# `cvx-kit/components/foundation` — the audited command protocol
+
+The Foundation is a Convex component that **owns zero tables and zero
+capability** — its schema is empty by design. What it provides is the
+application kernel: the `Command` protocol (validate → observe → execute →
+audit, in one transaction), the `Query` kernel, and payload-free
+`Observability`. It is declared **once** per app and everything destructures
+from it; there is no separate command import.
+
+## Mounting and declaring
+
+```ts
+// convex/convex.config.ts
+import { defineApp } from 'convex/server'
+import foundation from 'cvx-kit/components/foundation'
+
+const app = defineApp()
+app.use(foundation)
+export default app
+```
+
+```ts
+// convex/foundation.ts — declared once, the single kernel source
+import { Foundation } from 'cvx-kit/components/foundation'
+import { components } from './_generated/api'
+import { writeAuditEntry } from './audit'
+
+export const { Command, Query, observability } = new Foundation(
+  components.foundation,
+  {
+    observability: {
+      enabled: () => process.env.COMMAND_OBSERVABILITY_ENABLED === 'true',
+      classifyError: (error) => classify(error), // → { outcome: 'denied' | 'failed', errorCode }
+      writeAudit: (ctx, entry) => writeAuditEntry(ctx, entry),
+    },
+  },
+)
+```
+
+Host code consumes the Foundation **only through this facade** — never deep
+imports of the component's internal modules.
+
+## Defining commands — per domain
+
+Each domain declares a frozen registry of operations and derives typed
+executors from it. `classification` and `audit()` are **mandatory per
+operation** — auditing is type-enforced, not opt-in.
+
+```ts
+// convex/domain/documents/commands.ts
+import { z } from 'zod'
+import { Command } from '../../foundation'
+import { documents } from './schema'
+
+const operations = {
+  'documents.rename': Command.operation({
+    command: documents.commandInput.extend({ id: zid('documents') }),
+    result: z.object({ ok: z.literal(true) }).strict(),
+    classification: 'business',
+    audit: ({ command }) => ({
+      operation: 'documents.rename',
+      actorId: command.actorId,
+      aggregate: { type: 'document', id: command.id },
+      metadata: { title: command.title },
+    }),
+  }),
+} as const
+
+const commands = new Command<MutationCtx, typeof operations>(operations)
+
+export const executeRename = commands.exec({
+  operation: 'documents.rename',
+  handler: async (ctx, command) => {
+    await ctx.db.patch(command.id, { title: command.title })
+    return { ok: true }
+  },
+})
+```
+
+The public API layer then wraps the executor in an `authMutation` and passes
+`ctx.actor` in. Public functions stay thin adapters; domain logic lives behind
+`execute*` functions.
+
+## What one execution does, in order
+
+1. **Parse the command** through the operation's `command` schema (strict zod).
+2. **Observe**: start the observation clock.
+3. **Permission check** — if the operation declares `permission`, the
+   Foundation's injected `checkPermission(ctx, { permission, operation })`
+   runs; throw to deny. Declaring a permission with no injected checker
+   **fails closed** (`COMMAND_PERMISSION_NOT_CONFIGURED`).
+4. **Default guard** — the registry-wide guard passed as the Command's second
+   argument (`new Command(operations, { guard })`), if any.
+5. **Operation guard** — the operation's own `guard(ctx, command)`:
+   preconditions like state-machine legality, ownership beyond roles, or
+   invariants over the parsed command. Throw to deny — nothing has run yet,
+   so a denial is always clean.
+6. **Run the handler**; its return value is parsed through the `result` schema
+   — outputs are validated too.
+7. **Audit**: call the operation's `audit({ command, result }, ctx)`. If it
+   returns non-null, the entry (plus the operation's `classification`) is
+   written through the injected `writeAudit` — **in the same transaction** as
+   the handler's writes. Returning `null` skips the audit (the ontology
+   convention: failures are not audited). When the operation declares
+   `aggregates: [...]`, an audit whose `aggregate.type` is not in that
+   allowlist throws (`COMMAND_AGGREGATE_NOT_DECLARED`) — the audit
+   vocabulary is enforced, not advisory. The per-operation catalog is
+   introspectable as `commands.aggregates` for tests.
+8. **Emit the observation**: `{ operation, classification, outcome,
+   errorCode?, durationMs }` — completed, denied, or failed per
+   `classifyError`.
+
+### Guards and permissions
+
+```ts
+// convex/foundation.ts — permission semantics are host policy, injected once
+export const { Command, Query, observability } = new Foundation(
+  components.foundation,
+  {
+    observability: { ... },
+    checkPermission: (ctx, { permission }) =>
+      requirePermission(ctx.identity, permission),   // throw to deny
+  },
+)
+
+// domain/<module>/commands.ts
+const operations = {
+  '<entities>.publish': Command.operation({
+    command: <entities>.commandInput.extend({ id: zid('<entities>') }),
+    result: z.object({ ok: z.literal(true) }).strict(),
+    classification: 'business',
+    permission: '<domain>.manage',                    // checked first
+    aggregates: ['<aggregate-type>'],                 // audit vocabulary allowlist
+    guard: async (ctx, command) => {                  // precondition, pre-handler
+      const row = await requireTenantReference(ctx.tenant, () => ctx.db.get(command.id))
+      if (row.state !== 'draft') errors.throw({ code: 'INVALID_STATE' })
+    },
+    audit: ({ command }) => ({ ... }),
+  }),
+} as const
+
+const commands = new Command<MutationCtx, typeof operations>(operations, {
+  guard: (ctx) => assertNotReadonlyWindow(ctx),       // registry-wide default
+})
+```
+
+Guards deny by throwing; a denial before the handler never needs rollback
+because nothing has executed. Keep guards read-only — a guard that writes is
+a handler in disguise.
+
+If any step throws, the Convex transaction rolls back — handler writes and
+audit entry together. Audit and effects can never disagree.
+
+### Dynamic dispatch
+
+`exec` has a second overload for operation selection at runtime:
+
+```ts
+export const executeAny = commands.exec({
+  dispatcher: z.object({ kind: z.enum(OPERATION_KINDS) /* from constants.ts */ }),
+  select: (input) => `documents.${input.kind}` as const,
+  handler,
+})
+```
+
+An unconfigured operation throws `COMMAND_OPERATION_NOT_CONFIGURED`.
+
+## Observability — payload-free by construction
+
+Observations carry identifiers and a duration, never payloads. Events are
+silently dropped unless:
+
+- `enabled` resolves to `true`,
+- `operation` and `classification` match `/^[A-Za-z][A-Za-z0-9_.-]{0,159}$/`,
+- `errorCode` (when present) matches `/^[A-Z][A-Z0-9_]{0,95}$/`.
+
+Practical consequence: **dotted lowercase operation names**
+(`documents.rename`) and **UPPER_SNAKE error codes** are effectively
+mandatory. Every telemetry path is wrapped in try/catch — observability is
+behaviorally inert and can never change command behavior or mask the original
+failure. Default sink is one JSON line on `console.info`
+(`event: 'command.execution'`); inject `emit` to redirect.
+
+## `executeResultBoundary` — typed failures, but only while it's safe
+
+```ts
+import { executeResultBoundary } from 'cvx-kit/components/foundation'
+
+const result = await executeResultBoundary(ctx, () => run(), boundary)
+// Result<Value, Failure> = { ok: true, value } | { ok: false, error }
+```
+
+Semantics — read carefully, they are decided by **transaction state**, not by
+the error:
+
+- Success → `{ ok: true, value }`.
+- A failure the boundary recognizes (`dataOf(error)` non-undefined) is
+  returned as `{ ok: false, error }` **only if the transaction has produced no
+  effects yet** (nothing written, nothing scheduled — checked via
+  `ctx.meta.getTransactionMetrics()`).
+- If anything was already written or scheduled, the error is **rethrown** so
+  Convex rolls the transaction back — a returned failure after effects would
+  commit those effects.
+- Unrecognized errors and unreadable metrics always rethrow.
+
+Use it at the outermost edge of a mutation when the client needs a typed
+`Result` over the wire instead of a thrown error. `projectResult(result,
+onFailure)` unwraps on the caller side.
+
+## The `Query` kernel
+
+`Query` mirrors the pattern for reads: an injected `execute` receives
+`{ context, metadata, run }`, letting the host apply uniform read policy
+(authorization checks, tracing) around every domain query without the domains
+knowing. Metadata defaults are set at construction and merged per-executor.
+
+## Rules and footguns
+
+1. One `new Foundation(...)` per app, in `convex/foundation.ts`. Everything
+   else destructures from it.
+2. Never deep-import the component's `modules/*` or `result.ts` paths from app
+   code — the `client.ts` facade is the contract.
+3. The audit callback receives the ctx untyped (`never`); wiring a query ctx
+   into an audited command fails at runtime, not compile time. Commands run in
+   mutations.
+4. Name operations `domain.verb` and error codes `UPPER_SNAKE` or your
+   telemetry silently disappears (see regexes above).
+5. Keep operation registries frozen (`as const`) in the domain's
+   `commands.ts`; vocabulary tuples live in `constants.ts`.

package/docs/conventions.md

@@ -0,0 +1,291 @@
+# cvx-kit conventions — folder structure, file anatomy, and naming
+
+This is the kit's doctrine. Not a style suggestion: the structure below is
+what the kit's structural guarantees (auth, triggers, bounded reads, audited
+commands) assume, and what its recommended architecture tests enforce. Follow
+it as written; deviate only with a documented reason and a matching change to
+the tests.
+
+Names in `<angle brackets>` are placeholders for your vocabulary. Everything
+else — the folder roles, the file anatomy, the naming grammar — is fixed.
+
+---
+
+## 1. Folder structure
+
+```
+convex/
+  convex.config.ts
+  schema.ts
+  functions.ts
+  triggers.ts
+  foundation.ts
+  <component>.ts            (one per mounted component: audit.ts, approvals.ts, ...)
+  auth.ts  auth.config.ts  http.ts  crons.ts
+  api/
+    <entity>.ts
+  domain/
+    table.ts
+    shared/
+      <provider>.ts
+    <entity>/
+      schema.ts  table.ts  constants.ts  commands.ts  queries.ts
+      rules.ts  shared.ts  actions.ts
+      <workflow>.ts  <workflow>_functions.ts
+      __tests__/
+  components/               (only if you author portable components)
+    <name>/
+  __tests__/
+    setup.ts  architecture.test.ts  facades.test.ts
+```
+
+Three zones, three privileges:
+
+- **Root** — configuration and facades. May import kit modules, generated
+  code, and component clients. May NOT export public functions or contain
+  business decisions.
+- **`api/`** — the public surface. May import `functions.ts` constructors and
+  its entity's domain modules. May NOT contain business logic, private
+  helpers, or reads/writes beyond delegation.
+- **`domain/`** — all business logic. May import `functions.ts`,
+  `foundation.ts`, facades, `domain/shared/`, and its own entity directory.
+  May NOT import `api/`, sibling entities, `_generated/server` builders, or
+  component internals.
+
+Dependency direction is one-way: `api → domain → shared → kit`. Anything
+pointing the other way is a violation.
+
+### Module grain
+
+`domain/<entity>/` is really `domain/<module>/`: the directory is a **bounded
+context that may own several related tables**, not necessarily one. Two
+tables belong in the same module when a single command routinely writes both,
+or when one's vocabulary is meaningless without the other; otherwise they are
+separate modules. The file anatomy in §2 is unchanged — a module's
+`schema.ts` simply declares several `zodTable`s and its `table.ts` exports
+one merged map (combine maps in `domain/table.ts` with `createModule`, which
+rejects duplicate owners). A one-table module is the degenerate case, so
+small apps look exactly like before.
+
+Cross-module rules:
+
+- Sibling modules may import each other's `rules.ts` and `queries.ts`
+  **only** — never `commands.ts`: one module never mutates another's state.
+- A workflow that must atomically write across modules lives in an optional
+  `application/` layer above `domain/` (`application/<workflow>.ts`); `api/`
+  adapters then import `application/*` and their own module, never a second
+  module.
+
+---
+
+## 2. File anatomy — what each file contains, exactly
+
+Every file has one job. The lists below are exhaustive: if content isn't
+listed for a file, it doesn't belong there.
+
+### Universal file order
+
+Every source file reads from public purpose to private implementation:
+
+1. Imports.
+2. Exported API — types, schemas, constants, functions.
+3. File-local types and constants supporting the implementation.
+4. Private helpers as **named function declarations**, at the bottom.
+
+No helper implementations above the exported API. No helper
+arrow-function constants where a `function` declaration works. No barrel
+files (`index.ts` re-exports) anywhere inside `convex/`. No re-exporting
+another file's function to shorten an import.
+
+### Root files
+
+| File | Contains | Never contains |
+|---|---|---|
+| `convex.config.ts` | `defineApp()`, one `app.use(...)` per component, `defineApp({ env })` declarations, `export default app` | anything else |
+| `schema.ts` | `defineSchema(domainTables)` | table definitions, validators |
+| `functions.ts` | the single `createAuthFunctions<DataModel>()` call and its exported constructors | handlers, business policy beyond the injected config |
+| `triggers.ts` | `createTriggers()`, `timestamps`/`appendOnly`/`noDelete` registrations, calls to per-entity `register<Entity>Triggers` | trigger *logic* for a specific entity (that lives in the entity) |
+| `foundation.ts` | the single `new Foundation(...)`, destructured exports | command definitions |
+| `<component>.ts` | `new <Client>(components.<name>)` + minimal admin plumbing | workflow/business definitions |
+| `http.ts` | routes: verify signature → parse payload → delegate to a domain function | webhook business logic |
+| `crons.ts` | `cronJobs()` declarations targeting `internal.domain.<entity>...` | handler logic |
+
+### `api/<entity>.ts` — the adapter file
+
+One file per entity exposed to clients. Each exported function follows one
+template and stays within ~10 lines of glue:
+
+```ts
+export const <verb> = authMutation({
+  args: <entity>.commandInput.extend({ /* ids, etc. */ }),
+  returns: <resultSchema>,
+  handler: (ctx, args) => execute<Verb><Entity>(ctx, { ...args, actorId: ctx.actor.userId }),
+})
+
+export const list = authQuery({
+  args: { limit: z.number() },
+  returns: z.array(<entity>.publicDto),
+  handler: (ctx, { limit }) =>
+    ctx.include(ctx.db.query('<entities>'))
+      .matching('by_<field>', (ix) => ix.eq('<field>', ctx.actor.userId))
+      .execute(limit, (rows) => rows.map(<entity>.toPublicDto)),
+})
+```
+
+Adapters do four things — parse (boundary schemas), authorize (constructor
+choice), delegate (`execute*` with `ctx.actor`), project (`toPublicDto`).
+The moment an adapter needs a private helper or a business `if`, that code
+moves to the domain.
+
+### `domain/<entity>/schema.ts` — shapes only
+
+- The entity's single `zodTable(...)` call, with `serverFields`,
+  `commandFields`, `publicFields` decided deliberately.
+- DTO compositions derived from the table's boundaries
+  (`z.object({ ...<entity>.publicDto.shape, ... }).strict()`).
+- Inferred types (`export type <Entity> = z.infer<typeof <entity>.schema>`).
+- NO indexes, NO `defineTable`, NO enum literals (consume `constants.ts`).
+
+### `domain/<entity>/table.ts` — topology only
+
+```ts
+export const <entity>Tables = {
+  <entities>: <entity>.table
+    .index('by_<field>', ['<field>'])
+    .index('by_<field>_and_<field2>', ['<field>', '<field2>']),
+}
+```
+
+Registered in `domain/table.ts`, which merges all entity maps into
+`domainTables`. Shapes change with the data model; indexes change with query
+patterns — that's why they are separate files.
+
+### `domain/<entity>/constants.ts` — vocabularies
+
+Every finite value set the entity owns, one owner per vocabulary:
+
+```ts
+export const <ENTITY>_STATES = ['<a>', '<b>', '<c>'] as const
+export type <Entity>State = (typeof <ENTITY>_STATES)[number]
+```
+
+Schemas, validators, filters, transition maps, and tests consume the tuple.
+Transition maps are typed against the value type so an invalid literal cannot
+compile. Numeric limits and durations the entity owns also live here.
+
+### `domain/<entity>/commands.ts` — every state change
+
+1. The frozen operation registry: `Command.operation({ command, result,
+   classification, audit })` per operation, keys `'<entity>.<verb>'`.
+2. One `new Command<Ctx, typeof operations>(operations)`.
+3. Exported executors: `export const execute<Verb><Entity> = commands.exec(...)`.
+4. Private handler helpers at the bottom.
+
+Audit derivation lives here, next to the operation it describes. No reads
+that belong in `queries.ts`; no pure predicates that belong in `rules.ts`.
+
+### `domain/<entity>/queries.ts` — domain reads
+
+Read logic worth reusing beyond one adapter: multi-step lookups, DTO
+assembly, cross-index selection. Bounded like everything else.
+
+### `domain/<entity>/rules.ts` — pure invariants
+
+Predicates and transition checks with **no ctx and no db**: unit-testable
+business truth (`can<Verb>(doc, actor)`, `isTransitionLegal(from, to)`).
+Handlers call rules; rules never call handlers.
+
+### `domain/<entity>/shared.ts` — entity-private helpers
+
+Code shared by two or more files *of this entity*. If a second entity needs
+it, it moves to `domain/shared/` — never a sibling import.
+
+### `domain/<entity>/actions.ts` — external side effects
+
+Action-side logic using the shared provider clients from
+`domain/shared/<provider>.ts`. Domains import the shared client; they never
+instantiate their own vendor SDK.
+
+### `domain/<entity>/<workflow>.ts` + `<workflow>_functions.ts`
+
+The workflow/approval definition the entity owns, and its internal callback
+targets built with `system*` constructors. Callbacks re-validate everything:
+`normalizeId`, `resourceType` check, staleness guard.
+
+### `domain/shared/` — cross-entity, and only cross-entity
+
+One configured client per external provider (`<provider>.ts`), plus zod/util
+helpers genuinely used by multiple entities. This directory is not a dumping
+ground: code with one consumer moves back to that consumer.
+
+### Tests
+
+- `domain/<entity>/__tests__/` — behavioral tests for the entity, driven
+  through the real constructors (`t.withIdentity(...)`).
+- `convex/__tests__/architecture.test.ts` — the executable conventions;
+  every rule proved against a synthetic violating fixture first.
+- `convex/__tests__/facades.test.ts` — every `app.use` exactly once; no
+  private-child access.
+- `convex/__tests__/setup.ts` — env stubs for `defineApp({ env })` vars.
+- Test files are named `<subject>.test.ts` and live in a `__tests__/`
+  directory beside the code they test — never in a parallel top-level tree.
+
+---
+
+## 3. Naming grammar
+
+| Thing | Convention | Example shape |
+|---|---|---|
+| Entity directory | plural camelCase, matches table name | `domain/<entities>/` |
+| Table | plural camelCase | `<entities>` |
+| Fields | camelCase; foreign keys `<other>Id`; timestamps only via the kit | `ownerId`, `archivedAt` |
+| Index | `by_<field>` / `by_<field>_and_<field>`, declaration order, nested paths flattened with `_` | `by_ownerId_and_state_status` |
+| Command operation | `<entity>.<verb>` lowercase dotted; must match `/^[A-Za-z][A-Za-z0-9_.-]{0,159}$/` | `<entities>.approve` |
+| Error code | `UPPER_SNAKE`, matching `/^[A-Z][A-Z0-9_]{0,95}$/`, defined in one owner | `INVALID_REQUEST_BOUNDARY` |
+| Vocabulary tuple | `UPPER_SNAKE_CASE` `as const`; derived type PascalCase singular | `<ENTITY>_STATES` / `<Entity>State` |
+| Domain executor | `execute<Verb><Entity>` | `executeApprove<Entity>` |
+| Rule predicate | `can<Verb>` / `is<Condition>` | `canApprove`, `isTransitionLegal` |
+| Trigger registration | `register<Entity>Triggers(triggers)` | exported from the entity, called in root `triggers.ts` |
+| Internal-callback file | `<purpose>_functions.ts`, sibling of `<purpose>.ts` | `approval_functions.ts` |
+| zodTable export | camelCase plural, same as table | `export const <entities> = zodTable(...)` |
+| DTO schema | `<entity><Purpose>Dto` | `<entity>SummaryDto` |
+| Zod schema value | camelCase noun | `commandInput`, `publicDto` |
+| Type | PascalCase; no `I`/`T` prefixes | `<Entity>State` |
+| Test file | `<subject>.test.ts` in `__tests__/` | `commands.test.ts` |
+| Public function path | `api/<entity>:<fn>` — clients never call a root path | — |
+
+The two regexes are enforced at runtime: observability silently drops events
+whose operation/classification/errorCode don't match. The rest is enforced by
+the architecture tests — a naming rule without a test is a wish.
+
+---
+
+## 4. Import rules
+
+Allowed, per zone (anything not listed is forbidden):
+
+| From | May import |
+|---|---|
+| `api/<entity>.ts` | `functions.ts`, `domain/<entity>/*`, `domain/shared/*`, zod |
+| `domain/<entity>/*` | `functions.ts`, `foundation.ts`, component facades, `domain/shared/*`, own directory, generated `internal`/`api` (references only), kit modules |
+| `domain/shared/*` | kit modules, vendor SDKs (this is the ONLY home for vendor clients) |
+| root facades | kit modules, `components` from generated api |
+| `functions.ts` | `_generated/server` (the only file allowed to) |
+| `components/<name>/**` | its own directory + npm deps only — no host imports, no `process.env` |
+
+Forbidden everywhere: sibling-entity imports, `api/` from `domain/`,
+component internals (anything below a component's client facade),
+`makeFunctionReference`, barrel files.
+
+---
+
+## 5. Formatting and language
+
+- TypeScript strict; no `any` in exported signatures; `as never` only at kit
+  seams that document it.
+- Zod objects that cross a boundary are `.strict()` — always.
+- `Object.freeze` for registries and long-lived configuration objects.
+- Comments state constraints the code can't (`// Optional only for rows
+  created before <epoch>.`) — never narration of the next line.
+- One entity concept per file; when a file serves two purposes, split it
+  along the anatomy in §2.