cvx-kit 0.1.7 → 0.1.8

package/docs/crud.md

@@ -1,5 +1,9 @@
 # `cvx-kit/crud` — the CRUD command factory
 
+> This factory uses the deprecated Promise command facade and remains available
+> for existing consumers. For new Effect commands, use `createEffectCrud` from
+> `cvx-kit/effect`; see [domain integrations](./domain-operations.md).
+
 `createCrudCommands` generates the three standard operations every entity
 starts with — create, update, archive — from one zodTable declaration,
 **fully inside the audited command pipeline**: strict command inputs from

package/docs/domain-operations.md

@@ -4,7 +4,7 @@ Declare operations beside their handlers, inject the application's repositories,
 
 The complete TypeScript module below is mirrored in `test/domain-operation-guide-types.ts` for strict compilation. All TypeScript in this guide belongs to that one module; there are no standalone handler fragments. It uses public `cvx-kit/*` imports, real Convex builders, an injected document repository, and generated references from the native acceptance fixture. Its document schema and generic builders let the example compile independently; an application imports its own `mutation`, `query`, and internal builders from `./_generated/server`. The integrated rename portion imports the exact registry from `test/fixture-effect/convex/integratedRename.ts` and binds its real generated references. The document create/receipt example remains separate.
 
-The examples use the optional Effect adapter even for ordinary handlers. Consumers without Effect can keep the legacy `cvx-kit/components/foundation` surface and use the neutral contracts, errors, idempotency, workflow, and tool facades. Import `cvx-kit/effect` only when the application supplies its Effect peer.
+The examples use the recommended Effect command API even for ordinary handlers. The older `Foundation.Command` facade is deprecated and retained for existing consumers without Effect; use [the migration guide](./commands.md) when moving those domains. Neutral contracts, errors, idempotency, workflow, and tool facades remain available without Effect. Import `cvx-kit/effect` only when the application supplies its Effect peer.
 
 ## Declare a cohesive domain
 

package/docs/effect.md

@@ -5,7 +5,11 @@ runner. Handlers can return ordinary values, Promises, or Effects. Each
 registry returns a lazy Effect from `exec(operation, input, host)`; the API
 adapter provides request services and runs it once.
 
-Install Effect explicitly when opting in:
+This is the recommended command API. The older `Foundation.Command` facade
+and `exec({ operation, handler })` executor API are deprecated and retained for
+compatibility. Declare handlers inside `command({...})` for new command code.
+
+Install Effect explicitly:
 
 ```sh
 bun add effect@4.0.1
@@ -377,8 +381,15 @@ registry's lazy Effect to a shared API adapter. A normal async handler works
 in the cohesive declaration without a generator; wrap expected Promise failures
 only when you want a typed error channel.
 
-The [command migration guide](./commands.md) shows a complete legacy-to-Effect
-pair and the existing lifecycle contract. The [authentication guide](./auth.md)
+The [command guide](./commands.md) documents the current lifecycle and migration
+steps; the [deprecated API reference](./commands-legacy.md) retains old examples.
+The [authentication guide](./auth.md)
 shows how to wrap trusted custom builders with `effectZodApiBuilder`, so auth,
 tenancy, validators, row-level policies, and triggers run through their
 existing builder before Effect request services are provisioned.
+
+Optional request context can be added through the existing Effect API adapter's
+`context` callback. Bind selected registries with `commands.withContext(value)`
+and consume `ctx.commands.exec(name, input)` through the application's existing
+function helper names. Keep dependencies local to each feature; explicit execution
+and input-only command handlers remain supported. See [optional context injection](./command-context.md).

package/docs/llms.md

@@ -3,7 +3,7 @@
 > 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`,
+> `commands.md`, `effect.md`, `domain-operations.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`.
@@ -22,7 +22,13 @@
 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`.
+`convex ^1.45.0`, `zod ^4.5.4`; command implementations also install
+`effect >=4.0.1 <5` and import `cvx-kit/effect`.
+
+**Command API selection:** use `createEffectFoundation` and declare handlers
+inside `command({...})`. The older `Foundation.Command` Promise facade is
+deprecated. Its compatibility examples live in `commands-legacy.md`; do not
+copy that API into new implementations.
 
 ## Non-negotiable rules
 
@@ -31,27 +37,27 @@ function constructors, a trigger registry, an audited command protocol
 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 `systemQuery/systemMutation/systemAction` (internal).
+   `adminQuery/...` (public) or `systemQuery/systemMutation/systemAction` (internal),
+   wrapped once with `effectZodApiBuilder` when their handlers return Effects.
    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. Optional per-operation `permission` (checked via the
-   Foundation's injected `checkPermission`) and `guard(ctx, command)`
-   preconditions run BEFORE the handler, plus a registry-wide default guard
-   (`new Command(operations, { guard })`). Composable middleware
-   (`Command.middleware(async ({ context, next }) => ...)`) wraps
-   [guards → handler] via registry `middleware: [...]` and per-operation
-   `middleware: [...]` — `next({ context })` enriches downstream ctx, and
-   the chain's output is re-parsed by the result schema. Query takes the
-   same shape (`Query.middleware`, kernel + per-executor arrays). Order:
-   permission → registry middleware → operation middleware → default guard
-   → operation guard → handler → result parse → aggregates → audit.
+5. **State changes are Effect commands**: declare
+   `Command({ context, operations: ({ command }) => ({ ... }), defaults })`.
+   Each `command({ input, result, classification, handler, audit })` owns its
+   handler; handlers receive `(input, context)`. Execute with
+   `commands.exec(operation, input, host)` and return the lazy Effect through a
+   shared API builder. Never pass a handler to `exec` or run a nested
+   `Effect.runPromise`. Permission uses the injected `checkPermission(host, ...)`;
+   guards receive `(context, input)`. Per-operation middleware is one callback,
+   `next()` returns an Effect, and `next({ context })` enriches downstream ctx.
+   Order: input → context → permission → prepare/replay → middleware → default
+   guard → operation guard → handler → result parse → aggregates/audit → completion.
+   Audit writes stay in the mutation transaction. Failures must escape the
+   mutation for rollback; replay skips middleware, guards, handler, and audit.
 6. **Never write timestamps by hand.** `createdAt`/`updatedAt` are maintained
    by the `timestamps` trigger; `archivedAt` is the app-controlled soft-delete
    marker.
@@ -74,18 +80,19 @@ function constructors, a trigger registry, an audited command protocol
 
 | Import                          | Provides                                                                                                                                                                                                                                                                |
 | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cvx-kit`                       | everything below re-exported (except components' defaults)                                                                                                                                                                                                              |
+| `cvx-kit`                       | Non-Effect helpers and component clients; import the optional Effect facade explicitly from `cvx-kit/effect`. |
 | `cvx-kit/zod-table`             | `zodTable`, `tenantTable`, `createModule`, `paginated`, `zodVariantTable`, `jsonSafeZid`, `TIMESTAMP_FIELDS`                                                                                                                                                            |
+| `cvx-kit/effect`                | Recommended command/query API: `createEffectFoundation`, `effectApiBuilder`, `effectZodApiBuilder`, `createEffectCrud`, idempotency/workflow adapters and operation tools. |
 | `cvx-kit/auth`                  | `createAuthFunctions` (incl. optional `security` RLS config), `createInclude`, `defaultRoleMap`                                                                                                                                                                         |
 | `cvx-kit/tenancy`               | `createTenantRules`, `composeRules`, `requireTenantReference`, `assertTenantOwned`, `TENANT_FIELD`                                                                                                                                                                      |
-| `cvx-kit/crud`                  | `createCrudCommands` — create/update/archive from a zodTable, inside the command pipeline; `enrich` REQUIRED for tenantTables                                                                                                                                           |
+| `cvx-kit/crud`                  | Compatibility CRUD factory using the deprecated Promise command facade; use `createEffectCrud` from `cvx-kit/effect` for new domains. |
 | `cvx-kit/state-machine`         | `createStateMachine` — typed transitions from constants tuples; `assert` drops into command guards                                                                                                                                                                      |
 | `cvx-kit/middleware`            | `rateLimit` — packaged middleware over an injected rate-limiter instance; keyed by `ctx.tenant`, missing key = config error                                                                                                                                             |
 | `cvx-kit/webhooks`              | `createWebhookBoundary`, `recordWebhookEvent`, `webhookEventsTable` — raw-body verify, natural-key dedup in the mutation                                                                                                                                                |
 | `cvx-kit/agent-tools`           | `createAgentTools` — tool records from table masks; mutation handlers route through command executors                                                                                                                                                                   |
 | `cvx-kit/triggers`              | `createTriggers`, `timestamps`, `appendOnly`, `noDelete`, `tenantOwnership`, `Triggers`                                                                                                                                                                                 |
 | `cvx-kit/errors`                | `KitError`, `defaultErrors`, `ErrorFactory`                                                                                                                                                                                                                             |
-| `cvx-kit/components/foundation` | `Foundation` — the ONLY runtime export besides the default component config for `app.use`. Everything (`Command`, `Query`, `observability`, `executeResultBoundary`, `projectResult`, `emitSemanticEvent`) destructures from the instance; nothing is importable loose. |
+| `cvx-kit/components/foundation` | Component client and types; `Foundation.Command` is deprecated. The component and other capabilities remain available. New command registries use `cvx-kit/effect`. |
 | `cvx-kit/components/approvals`  | `Approvals` client; default export = component config for `app.use`                                                                                                                                                                                                     |
 | `cvx-kit/test`                  | `registerFoundation(t)`, `registerApprovals(t)` for convex-test                                                                                                                                                                                                         |
 
@@ -110,7 +117,7 @@ appendOnly(triggers, 'history')
 // convex/functions.ts
 export const {
 	authQuery,
-	authMutation,
+	authMutation: baseAuthMutation,
 	authAction,
 	adminQuery,
 	adminMutation,
@@ -141,13 +148,23 @@ export const {
 	},
 })
 
+// convex/functions.ts — wrap configured auth constructors once, after auth/RLS/triggers
+// Import Context from effect and effectZodApiBuilder from cvx-kit/effect.
+// Place this after the registry declaration or import the registry from its module.
+export const authMutation = effectZodApiBuilder(baseAuthMutation, {
+	context: (ctx) => ({ commands: commands.withContext(ctx) }),
+})
+
 // convex/foundation.ts
-export const { Command, Query, observability } = new Foundation(components.foundation, {
+// Import createEffectFoundation from cvx-kit/effect.
+import type { MutationCtx } from './_generated/server'
+export type CommandHost = MutationCtx & { actor: { userId: string } }
+export const { Command, Query, observability } = createEffectFoundation({
 	observability: {
 		enabled: () => process.env.OBS === 'true',
 		classifyError, // → { outcome: 'denied'|'failed', errorCode }
-		writeAudit: (ctx, entry) => writeAuditEntry(ctx, entry),
 	},
+	writeAudit: (ctx: CommandHost, entry) => writeAuditEntry(ctx, entry),
 })
 
 // convex/approvals.ts
@@ -175,32 +192,33 @@ export const documents = zodTable(
 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 },
+export const renameInput = documents.commandInput.extend({ id: zid('documents') })
+export const renameResult = z.object({ ok: z.literal(true) }).strict()
+export const commands = Command({
+	context: (host: CommandHost) => host,
+	operations: ({ command }) => ({
+		'documents.rename': command({
+			input: renameInput,
+			result: renameResult,
+			classification: 'business',
+			handler: async (input, ctx) => {
+				await ctx.db.patch(input.id, { title: input.title })
+				return { ok: true as const }
+			},
+			audit: ({ command }, ctx) => ({
+				operation: 'documents.rename',
+				actorId: ctx.actor.userId,
+				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 }),
+	args: renameInput,
+	returns: renameResult,
+	handler: (ctx, input) => ctx.commands.exec('documents.rename', input),
 })
 export const list = authQuery({
 	args: { limit: z.number() },
@@ -261,9 +279,15 @@ points at `runId`.
 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.
+6. Command audit actors come from trusted host context, never client input.
+   Commands with writes must run through mutation builders with wrapped `ctx.db`.
 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.
+
+Optional request context can be added through the existing Effect API adapter's
+`context` callback. Bind selected registries with `commands.withContext(value)`
+and consume `ctx.commands.exec(name, input)` through the application's existing
+function helper names. Keep dependencies local to each feature; explicit execution
+and input-only command handlers remain supported. See [optional context injection](./command-context.md).

package/docs/migration.md

@@ -25,7 +25,7 @@ convex/
   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
+  foundation.ts               # the single createEffectFoundation(...) 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

package/docs/upgrading.md

@@ -1,5 +1,14 @@
 # Upgrading to 0.1.0 — the new way of things
 
+## Current command API — Effect declarations
+
+`Foundation.Command` and its separate `exec({ operation, handler })` API are
+deprecated. For new command code, use `createEffectFoundation` from
+`cvx-kit/effect`, declare handlers inside `command({...})`, and return
+`exec(operation, input, host)` through a shared Effect API builder.
+See [commands.md](./commands.md) for migration steps. Existing consumers remain
+compatible; older release sections below describe their historical APIs.
+
 ## 0.1.6 — stricter architecture checks
 
 Enable `project-structure`, `root-wiring-only`, `application-orchestration`,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cvx-kit",
-	"version": "0.1.7",
+	"version": "0.1.8",
 	"description": "Reusable Convex application kit: foundation kernels, approvals component, zod table boundaries, WorkOS-backed auth function constructors, and audited command protocol.",
 	"keywords": [
 		"component",

package/scripts/test-packed-effect.mjs

@@ -26,8 +26,11 @@ const domainGuideImports = new Set([
 	'./fixture-effect/convex/_generated/dataModel',
 ])
 const extraTypeFixtures = [
+	join(root, 'README.md'),
 	join(root, 'src/docs/effect.md'),
 	join(root, 'src/docs/commands.md'),
+	join(root, 'src/docs/command-context.md'),
+	join(root, 'src/docs/commands-legacy.md'),
 	join(root, 'src/docs/auth.md'),
 	domainGuidePath,
 	...process.argv.slice(2).map((path) => resolve(path)),