cvx-kit 0.0.1 → 0.0.2

package/README.md

@@ -23,6 +23,22 @@ bun add cvx-kit
   target ES2025, minified, deps external, publint-verified
 - `bun run build:codegen` — re-run `convex codegen` for both components, then build
 
+## Documentation
+
+Full docs ship with the package — `node_modules/cvx-kit/docs/` when installed,
+authored in [`src/docs/`](./src/docs/):
+
+- [`architecture.md`](./src/docs/architecture.md) — the layered application shape the kit encodes
+- [`conventions.md`](./src/docs/conventions.md) — the doctrine: folder structure, file anatomy, naming grammar, import rules
+- [`zod-table.md`](./src/docs/zod-table.md) — one zod shape per entity, masked into every boundary
+- [`auth.md`](./src/docs/auth.md) — auth-aware function constructors from injected policy
+- [`commands.md`](./src/docs/commands.md) — Foundation, the audited command protocol, observability
+- [`triggers.md`](./src/docs/triggers.md) — trigger registry, timestamps/append-only/no-delete
+- [`approvals.md`](./src/docs/approvals.md) — declarative approval workflows
+- [`maintainability.md`](./src/docs/maintainability.md) — keeping a Convex app maintainable long-term
+- [`migration.md`](./src/docs/migration.md) — restructuring an existing raw Convex project into this architecture
+- [`llms.md`](./src/docs/llms.md) — condensed reference to paste into an LLM/agent context
+
 ## Modules
 
 ### `cvx-kit/zod-table`

package/docs/approvals.md

@@ -0,0 +1,152 @@
+# `cvx-kit/components/approvals` — declarative approval workflows
+
+A self-contained Convex component for human-in-the-loop approval flows:
+declarative step lists (decision / branch / mutation / action / notify) with
+count quorum, maker-checker, expiry, compatibility keys, durable execution via
+a **nested** `@convex-dev/workflow`, and its own audit trail via a **nested**
+`convex-audit-log`. The component never imports host code: tenancy is an
+opaque `scopeRef`, resources are opaque `resourceType`/`resourceRef` strings,
+and callbacks cross the boundary as **function handles**.
+
+## Mounting
+
+```ts
+// convex/convex.config.ts
+import approvals from 'cvx-kit/components/approvals'
+app.use(approvals)
+```
+
+The component mounts its own private `workflow` and `auditLog` children. Do
+**not** re-register those children at the app root under the same identity,
+and never reach into `components.approvals.workflow` / `.auditLog` from host
+code — the `Approvals` client class is the only contract.
+
+```ts
+// convex/approvals.ts — host facade, declared once
+import { Approvals } from 'cvx-kit/components/approvals'
+import { components } from './_generated/api'
+
+export const approvals = new Approvals(components.approvals)
+```
+
+## Defining a workflow — in the owning domain
+
+Workflow *definitions* are business logic and live in the domain that owns the
+resource, not in the root facade:
+
+```ts
+// convex/domain/documents/approval.ts
+import { approvals } from '../../approvals'
+import { internal } from '../../_generated/api'
+
+export const publishApproval = approvals.define({
+  name: 'documentPublish',
+  steps: [
+    approvals.decision('managerDecision', {
+      decisions: ['approved', 'rejected'],
+      quorum: { kind: 'count', approvals: 1 },
+      makerChecker: true,                  // requester cannot decide
+      expiresAfterMs: 7 * 24 * 60 * 60 * 1000,
+    }),
+    approvals.branch('applyDecision', {
+      approvedStepKey: 'publishDocument',
+      rejectedStepKey: 'notifyRejected',
+    }),
+    approvals.mutation('publishDocument', {
+      handler: internal.domain.documents.approval_functions.applyDecision,
+    }),
+    approvals.notify('notifyRejected', {
+      handler: internal.domain.documents.approval_functions.notifyRejected,
+      retry: true,
+    }),
+  ],
+})
+```
+
+### Step kinds
+
+| Step | Runs | Notes |
+|---|---|---|
+| `decision(key, { decisions, quorum, makerChecker?, expiresAfterMs? })` | waits for humans | quorum is `{ kind: 'count', approvals: n }`; expiry resolves the run as `expired` |
+| `branch(key, { approvedStepKey, rejectedStepKey })` | routing | jumps by the preceding decision's outcome |
+| `mutation(key, { handler, retry? })` | internal mutation handle | transactional apply step |
+| `action(key, { handler, retry? })` | internal action handle | side effects (third parties) |
+| `notify(key, { handler, retry? })` | internal action handle | semantically a notification; same contract as action |
+
+Limits (enforced by the component's validators): ≤ 32 steps per workflow,
+≤ 8 decisions per decision step, names ≤ 96 chars, references ≤ 256 chars,
+metadata ≤ 32 entries (keys ≤ 64, values ≤ 512 chars).
+
+### Compatibility keys
+
+`compatibilityKey` (defaults to `name`) versions the workflow shape. Every
+`decide`/`cancel`/`status`/`restart` call sends it, so a run started under an
+old definition cannot be driven by an incompatible new one. When you change a
+workflow's steps in a breaking way, change the key.
+
+## Driving a run
+
+```ts
+// start — from an authMutation, with ctx.actor as the requester
+const { runId } = await publishApproval.start(ctx, {
+  scopeRef: ctx.org.organizationId,        // opaque tenancy
+  resourceType: 'document',
+  resourceRef: documentId,                 // opaque to the component
+  requester: ctx.actor,
+  metadata: { title },                     // bounded string map
+})
+
+// decide — a manager approves or rejects
+await publishApproval.decide(ctx, { runId, decision: 'approved', reason }, ctx.actor)
+
+// observe
+await publishApproval.status(ctx, runId)   // pending | approved | rejected | expired | canceled
+await publishApproval.evidence(ctx, runId) // per-step decision evidence
+await publishApproval.list(ctx, { scopeRef, ... })
+
+// manage
+await publishApproval.cancel(ctx, runId, ctx.actor)
+await publishApproval.restart(ctx, runId)
+await approvals.cleanupAudit(ctx, { olderThanDays: 365, batchSize: 100 })
+```
+
+## Callback handlers — validate everything coming back
+
+Step handlers are **internal** functions (build them with `systemMutation` /
+`systemAction`). They receive `ApprovalCallbackInput`: `{ runId, scopeRef,
+resourceType, resourceRef, metadata?, decision? }` — all opaque strings.
+Because the component cannot know your tables, the handler must re-establish
+trust:
+
+```ts
+export const applyDecision = systemMutation({
+  args: approvalCallbackArgs,
+  handler: async (ctx, input) => {
+    if (input.resourceType !== 'document') throw new Error('WRONG_RESOURCE')
+    const id = ctx.db.normalizeId('documents', input.resourceRef)
+    if (!id) throw new Error('BAD_REF')
+    const document = await ctx.db.get(id)
+    // guard against stale runs: the doc must still point at this run
+    if (document?.approvalRunId !== input.runId) return
+    await ctx.db.patch(id, { reviewState: 'published' })
+  },
+})
+```
+
+That `approvalRunId` check is the idempotency/staleness guard from the origin
+app — copy it.
+
+## Rules and footguns
+
+1. Root facade (`convex/approvals.ts`) instantiates the client; workflow
+   *definitions* live in the owning domain.
+2. Handlers get opaque strings — always `normalizeId`, re-check
+   `resourceType`, and verify the resource still references the run.
+3. `makerChecker: true` means the requester's decisions are rejected — design
+   your UI accordingly.
+4. The component keeps its own audit trail (retention category
+   `approval-protocol`, cleanup via `cleanupAudit`, retention 1–3650 days,
+   batch ≤ 100). Host-side business audit still goes through your command
+   protocol — they are different trails.
+5. Changing steps without changing `compatibilityKey` lets old runs be driven
+   by a new incompatible shape; bump the key on breaking changes.

package/docs/architecture.md

@@ -0,0 +1,124 @@
+# Architecture — the shape of a cvx-kit application
+
+cvx-kit was extracted from a production Convex application (~12k LOC backend).
+This document describes the architecture that application follows and that the
+kit is designed to reproduce: strict ownership boundaries, injected policy,
+portable components, and conventions that are *executable* (enforced by tests)
+rather than aspirational.
+
+## The layers
+
+```
+convex/
+  convex.config.ts        # component mounting — each app.use(x) exactly once
+  schema.ts               # defineSchema(domainTables) — nothing else
+  functions.ts            # createAuthFunctions(...) — the ONLY place raw builders appear
+  foundation.ts           # const { Command, Query, observability } = new Foundation(...)
+  approvals.ts            # const approvals = new Approvals(components.approvals)
+  audit.ts                # writeAuditEntry over convex-audit-log + admin readers
+  triggers.ts             # the single Triggers registry + helper registrations
+  auth.ts / auth.config.ts / http.ts   # identity provider wiring (e.g. WorkOS AuthKit)
+  api/                    # PUBLIC surface — thin adapters only
+    <documents>.ts          #   authQuery/authMutation wrapping domain executors
+  domain/
+    table.ts              # merges per-domain table maps into domainTables
+    shared/               # genuinely cross-entity helpers only
+    <entity>/            # one directory per entity/aggregate
+      schema.ts           #   zodTable declaration (shapes only)
+      table.ts            #   indexes attached to <zodTable>.table
+      constants.ts        #   finite vocabularies (UPPER_SNAKE readonly tuples)
+      commands.ts         #   operation registry + executors (new Command(...))
+      queries.ts          #   domain read logic
+      approval.ts         #   approvals.define(...) workflow definitions
+      *_functions.ts      #   internal callbacks (systemMutation/systemAction)
+```
+
+### Layer rules
+
+1. **`api/` is the only public surface.** It contains no bare `query(` or
+   `mutation(` — only `auth*`/`role*`/`admin*` constructors delegating to
+   domain `execute*` functions. Public functions are adapters: parse, pass
+   `ctx.actor`, project DTOs.
+2. **`domain/<entity>/` owns everything about the entity** — its zod shape,
+   indexes, vocabularies, commands, queries, workflows. Cross-domain reuse
+   goes through `domain/shared/`, never sibling imports of another domain's
+   internals.
+3. **Root files are facades over mounted components.** `foundation.ts`,
+   `approvals.ts`, `audit.ts` configure infrastructure; business definitions
+   stay in the owning domain.
+4. **Internal functions use `systemMutation`/`systemAction`** — never raw
+   `internalMutation(`/`internalAction(` — so triggers and `include` apply to
+   scheduled/callback work too.
+
+## Injection, not import
+
+The kit's central design rule: **library code never imports app singletons**.
+Every kit surface takes its policy as a parameter:
+
+- `createAuthFunctions` receives the generated builders, `getAuthUser`,
+  `mapRole`, `verifyMembership`, `triggers`, `errors`.
+- `Foundation` receives `classifyError`, `writeAudit`, the `enabled` flag.
+- `Approvals` receives only its component reference; host data crosses as
+  opaque validated strings.
+
+The reverse rule holds for components: a portable component must not import
+host domains, generated host APIs, environment configuration, or vendor SDKs
+(WorkOS, Drizzle, Redis…). Host values cross its public API only as
+**validated, bounded, opaque data** — `scopeRef`, `resourceRef`, function
+handles. Component schemas contain only their own records and never mirror a
+private child component's tables.
+
+## Boundaries as schemas
+
+Data crossing any boundary is a zod schema derived from one `zodTable`
+declaration per entity (see `zod-table.md`):
+
+- storage → `defineTable` via `zodToConvex`
+- writes → `insertSchema`/`updateSchema` (server fields and timestamps
+  excluded)
+- commands → `commandInput` (explicit allowlist)
+- clients → `publicDto` + `toPublicDto` (runtime redaction)
+- LLM tools → `tools.*` and `jsonSafeZid`
+
+Everything is `.strict()`. There is exactly one source of truth per entity and
+no boundary that "just trusts" its input.
+
+## Writes as commands
+
+State changes flow through the audited command protocol (see `commands.md`):
+parse input → observe → run handler → parse output → write audit — one
+transaction, rollback-consistent. Classifications and audit derivation are
+type-required per operation. Human-gated changes use the approvals component;
+its apply steps are commands too.
+
+## Conventions worth enforcing with tests
+
+The origin app enforces its architecture with a test suite that raw-globs the
+source and asserts violations — each rule proved against a synthetic fixture
+first so the checker can't silently pass. Highly recommended for consumers:
+
+- **No inline tables/schemas** — `defineTable`/`defineSchema` only in
+  `table.ts`/`schema.ts`.
+- **No inline enums** — `z.enum([...])` with an inline array literal is
+  banned; vocabularies are named `UPPER_SNAKE` tuples in `constants.ts`.
+- **No deep server imports** — components consumed only through their
+  `client.ts` facade; explicit allowlist for exceptions.
+- **No handwritten references** — `makeFunctionReference` banned; use
+  generated `internal`/`api`.
+- **No sibling-domain imports** — a domain reaches another only via
+  `domain/shared/` or the public API.
+- **Facades mount once** — every `app.use(x)` appears exactly once; facades
+  never reach a component's private children.
+- **Component boundary tests** — no host imports, no
+  `process.env`/vendor-SDK references inside `components/*`.
+- **Copyability** — copy the component to a tmpdir with only its package
+  deps, run `tsc`: proves portability continuously.
+
+## Component mounting order
+
+In `convex.config.ts`, mount infrastructure before consumers: auth kit →
+foundation → audit log → approvals → named workflow/workpool instances. Use
+`app.use(x, { name })` when mounting the same component twice; `components.
+<name>` keys off that name. Required env vars can be declared on
+`defineApp({ env: { ... } })` so deploys fail fast — remember to stub them in
+test setup.

package/docs/auth.md

@@ -0,0 +1,157 @@
+# `cvx-kit/auth` — auth-aware function constructors from injected policy
+
+`createAuthFunctions` builds the function constructors your whole backend uses
+in place of raw `query`/`mutation`/`action`. Nothing in the kit imports your
+app's singletons — identity resolution, role vocabulary, membership
+verification, trigger wrapping, and error policy are all **injected** by the
+host. The kit provides the structure; the app provides the policy.
+
+## Setup — declared once per app
+
+```ts
+// convex/functions.ts (the single place constructors are built)
+import { createAuthFunctions, defaultRoleMap } from 'cvx-kit/auth'
+import {
+  action, internalAction, internalMutation, mutation, query,
+} from './_generated/server'
+import type { DataModel } from './_generated/dataModel'
+import { triggers } from './triggers'
+import { authKit } from './auth'
+
+export const {
+  authQuery, authMutation, authAction,
+  roleQuery, roleMutation, roleAction,
+  adminQuery, adminMutation, adminAction,
+  systemMutation, systemAction,
+  include, authenticatedUser,
+} = createAuthFunctions<DataModel>({
+  query, mutation, action, internalMutation, internalAction,
+  getAuthUser: (ctx) => authKit.getAuthUser(ctx),
+  mapRole: defaultRoleMap,          // or your own vocabulary (see below)
+  adminRoles: ['admin'],
+  triggers,                          // every mutation write runs through wrapDB
+  verifyMembership: async ({ userId, organizationId }) => {
+    const memberships = await authKit.workos.userManagement
+      .listOrganizationMemberships({ organizationId, userId, statuses: ['active'] })
+    const m = memberships.data.find((c) => c.userId === userId)
+    return m ? { organizationId: m.organizationId, roleSlug: m.role.slug } : null
+  },
+})
+```
+
+Every function in the app is then built from these — raw `query`/`mutation`
+imports from `_generated/server` appear **only** in this file.
+
+## The constructor families
+
+| Constructor | Visibility | Auth | Extra |
+|---|---|---|---|
+| `authQuery` / `authMutation` / `authAction` | public | any authenticated org member | actions live-verify membership |
+| `roleQuery(...roles)` / `roleMutation(...)` / `roleAction(...)` | public | listed roles only | factory — call with your roles |
+| `adminQuery` / `adminMutation` / `adminAction` | public | `config.adminRoles` | pre-built `role*(...adminRoles)` |
+| `systemMutation` | internal | none (trusted caller) | still trigger-wrapped |
+| `systemAction` | internal | none | plain internal action |
+
+All are `zCustom*` constructors from convex-helpers, so `args` and `returns`
+take zod schemas directly and compose with `zodTable` masks.
+
+## What handlers receive on `ctx`
+
+Authenticated constructors extend the ctx with a frozen auth bundle:
+
+- `ctx.identity` — the raw `UserIdentity` (JWT claims)
+- `ctx.user.id` — the synchronized principal id (from `getAuthUser`)
+- `ctx.org` — `{ organizationId, role }`
+- `ctx.role` — the mapped role
+- `ctx.actor` — `{ userId, organizationId, role }` — pass this to audits,
+  approvals, and commands as the canonical actor reference
+- `ctx.include` — the bounded query builder (below)
+
+`systemMutation` gets `include` and trigger wrapping but no auth bundle.
+
+## Role vocabulary is per-app
+
+`mapRole` maps the identity's role slug onto **your** role union; returning
+`null` rejects with `FORBIDDEN`, so unknown roles never pass. The default
+(`defaultRoleMap`) is WorkOS-flavored: `member → writer`, and
+`reader`/`writer`/`admin` pass through.
+
+Supply your own vocabulary via the generic:
+
+```ts
+createAuthFunctions<DataModel, 'viewer' | 'editor' | 'owner'>({
+  mapRole: (slug) => (slug === 'owner' ? 'owner' : slug === 'editor' ? 'editor' : slug ? 'viewer' : null),
+  adminRoles: ['owner'],
+  ...
+})
+```
+
+## Queries/mutations trust the JWT; actions re-verify
+
+Queries and mutations read org and role from the identity token. Actions —
+which can run long and call third parties — additionally call
+`verifyMembership` **live** before the handler runs, and the fresher
+role/organization from that check replaces the JWT's. Verification **fails
+closed**: any error or org mismatch throws `FORBIDDEN`. Omit
+`verifyMembership` to let actions trust the JWT like queries do.
+
+## Mutations are structurally trigger-wrapped
+
+When `triggers` (or `wrapDB`) is configured, every `authMutation`,
+`roleMutation`, and `systemMutation` runs its writes through
+`triggers.wrapDB(ctx)`. Trigger enforcement (timestamps, append-only,
+no-delete, denormalization) is therefore **structural** — a handler cannot
+forget it, because it never sees an unwrapped `ctx.db`. This is the reason raw
+`mutation` must not be used outside `functions.ts`.
+
+## `include()` — every read is bounded
+
+`include` wraps a table query in a fluent selector that (a) picks the first
+matching indexed query and (b) refuses unbounded reads. `execute(limit)`
+rejects limits outside `1..maxRows` (default 100, configurable via
+`maxIncludedQueryRows`).
+
+```ts
+export const list = authQuery({
+  args: { ownerId: zid('users').optional(), limit: z.number() },
+  returns: z.array(documents.publicDto),
+  handler: (ctx, args) =>
+    ctx.include(ctx.db.query('documents'))
+      .when(args.ownerId, (q, ownerId) =>
+        q.withIndex('by_owner', (ix) => ix.eq('ownerId', ownerId)))
+      .otherwise((q) => q.withIndex('by_owner'))
+      .execute(args.limit, (rows) => rows.map(documents.toPublicDto)),
+})
+```
+
+Selector methods:
+
+- `.when(value, select)` — if `value` is non-null and nothing selected yet,
+  use `select(query, value)`.
+- `.matching(indexName, range?, shouldMatch?)` — index selection with an
+  optional guard boolean.
+- `.otherwise(select)` — fallback, returns the raw `Query`.
+- `.resolve()` — selected query or full table scan (escape hatch).
+- `.execute(limit, transform?)` — bounded `take` + optional projection. This
+  is the normal terminal.
+
+## Errors
+
+All rejections go through the injected `ErrorFactory` (default: throws
+`KitError` with codes `UNAUTHENTICATED`, `FORBIDDEN`,
+`INVALID_REQUEST_BOUNDARY`). Hosts with their own error taxonomy adapt it:
+
+```ts
+errors: { throw: (input) => { throw App.errors.from(input) } }
+```
+
+## Rules of thumb
+
+1. Build constructors once in `convex/functions.ts`; import them everywhere
+   else. Raw `_generated/server` builders appear nowhere else.
+2. Public functions: `auth*`/`role*`/`admin*`. Scheduled/internal work:
+   `system*`. Never expose an unauthenticated public function unless it is
+   deliberately anonymous (and then document why).
+3. Reads go through `ctx.include(...)` with an explicit limit.
+4. Use `ctx.actor` as the actor reference in audits and approvals — never
+   re-derive identity in a handler.

package/docs/commands.md

@@ -0,0 +1,177 @@
+# `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. **Run the handler**; its return value is parsed through the `result` schema
+   — outputs are validated too.
+4. **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).
+5. **Emit the observation**: `{ operation, classification, outcome,
+   errorCode?, durationMs }` — completed, denied, or failed per
+   `classifyError`.
+
+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`.