cvx-kit 0.1.15 → 0.1.16

package/docs/approvals.md

@@ -1,201 +0,0 @@
-# `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/convex.config'
-app.use(approvals)
-```
-
-After installation or upgrade, deploy once and run the component health query
-from a host wrapper:
-
-```ts
-return ctx.runQuery(components.approvals.health.check, {})
-```
-
-It returns the installed approvals schema version and required index names. It
-also executes reads through
-`approvalDecisions.by_runId_and_decidedAt` and
-`approvalDecisions.by_runId_and_stepKey_and_actor_actorRef`, failing with an
-installation-specific diagnostic if the packaged component schema was not
-deployed.
-
-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 from a host query
-await publishApproval.status(ctx, runId) // pending | approved | rejected | expired | canceled
-await publishApproval.evidence(ctx, runId) // per-step decision evidence
-await publishApproval.list(ctx, {
-	scopeRef,
-	state: 'pending',
-	paginationOpts: { cursor: null, numItems: 20 },
-})
-
-// 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
-import { approvalCallbackArgs } from 'cvx-kit/components/approvals'
-
-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.
-
-For branch callbacks, `decision.evidence` contains
-`{ stepKey, actorRef, decision, reason?, decidedAt }` items. Use the exported
-`approvalCallbackArgs` validator instead of duplicating that protocol boundary.
-
-### Paginated inboxes
-
-Expose the configured workflow through a host query; component pagination uses
-`convex-helpers` internally because Convex's built-in `.paginate()` is not
-available inside components:
-
-```ts
-export const approvalInbox = authQuery({
-	args: {
-		state: z.enum(['pending', 'approved', 'rejected', 'expired', 'canceled']).optional(),
-		paginationOpts: convexToZod(paginationOptsValidator),
-	},
-	handler: (ctx, args) =>
-		publishApproval.list(ctx, {
-			scopeRef: ctx.org.organizationId,
-			...args,
-		}),
-})
-```
-
-The result keeps Convex's standard pagination shape, so React consumers can
-call `usePaginatedQuery(api.approvals.approvalInbox, { state: 'pending' },
-{ initialNumItems: 20 })`. Pass each returned cursor only back to the same
-scope/state query.
-
-## 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

@@ -1,124 +0,0 @@
-# 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 } = createEffectFoundation(...)
-  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         #   Command({ context, operations }) with handlers inside 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`.
-- `createEffectFoundation` 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.