cvx-kit 0.1.6 → 0.1.8

package/docs/effect.md

@@ -0,0 +1,395 @@
+# Effect domain commands and queries
+
+`cvx-kit/effect` adds cohesive command/query declarations and a shared API
+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.
+
+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
+```
+
+The optional peer range is `>=4.0.1 <5`. Existing imports and Promise-based
+Foundation consumers work without Effect installed. Use the public facade;
+the internal module paths are not supported imports.
+
+## A complete domain-to-API example
+
+These four TypeScript sections form one module and are compiled together
+against the packed public package. The example uses Convex's generic builders
+with a concrete schema so it is standalone. In an app, put the schema in
+`convex/schema.ts`, import your generated `query`, `mutation`, `QueryCtx`, and
+`MutationCtx` from `./_generated/server`, and split the remaining code into
+services, domain registries, shared API setup, and endpoint modules.
+
+The API obtains the actor from authenticated Convex identity. Caller arguments
+contain only a document key and title. Both services constrain document reads
+and writes by that actor; the application should also enforce its own roles
+and tenant policies. The small permission checker below only requires a
+nonempty trusted actor.
+
+### Contracts and injectable capabilities
+
+The reader has no write methods. The mutation provider will add the writer;
+a native query cannot satisfy a command's writer requirement. Expected errors
+are values in the Effect error channel, rather than thrown exceptions.
+
+```ts
+import { Context, Effect } from 'effect'
+import {
+	defineSchema,
+	defineTable,
+	queryGeneric,
+	mutationGeneric,
+	type DataModelFromSchemaDefinition,
+	type QueryBuilder,
+	type MutationBuilder,
+	type GenericQueryCtx,
+	type GenericMutationCtx,
+} from 'convex/server'
+import { ConvexError, v } from 'convex/values'
+import { z } from 'zod'
+import { createEffectFoundation, effectApiBuilder } from 'cvx-kit/effect'
+import type { AuditEntryInput } from 'cvx-kit/components/foundation'
+
+export const schema = defineSchema({
+	documents: defineTable({ key: v.string(), owner: v.string(), title: v.string() }).index(
+		'by_owner_key',
+		['owner', 'key'],
+	),
+	audits: defineTable({ actor: v.string(), operation: v.string(), documentKey: v.string() }),
+})
+type DataModel = DataModelFromSchemaDefinition<typeof schema>
+type QueryCtx = GenericQueryCtx<DataModel>
+type MutationCtx = GenericMutationCtx<DataModel>
+const nativeQuery: QueryBuilder<DataModel, 'public'> = queryGeneric
+const nativeMutation: MutationBuilder<DataModel, 'public'> = mutationGeneric
+
+type Host = { actor: string }
+class DocumentMissing {
+	readonly _tag = 'DocumentMissing'
+}
+class RenameRejected {
+	readonly _tag = 'RenameRejected'
+}
+class AccessDenied {
+	readonly _tag = 'AccessDenied'
+}
+class DocumentReader extends Context.Service<
+	DocumentReader,
+	{ title: (key: string, actor: string) => Effect.Effect<string, DocumentMissing> }
+>()('DocumentReader') {}
+class DocumentWriter extends Context.Service<
+	DocumentWriter,
+	{
+		rename: (key: string, title: string, actor: string) => Effect.Effect<void, DocumentMissing>
+		audit: (actor: string, entry: AuditEntryInput) => Effect.Effect<void>
+	}
+>()('DocumentWriter') {}
+```
+
+### Cohesive domain declarations
+
+`label` is an ordinary async handler, and `preview` uses a generator. `title` uses `Effect.fn` with explicit input
+and host annotations. `rename` returns an `Effect.gen` program, yields the
+query directly, then uses the injected writer. Its pipe converts the query's
+missing-document error into a domain-specific rename rejection before adding
+a span. The audit entry sits beside the command, and the shared audit policy
+uses the same invocation's writer.
+
+```ts
+const foundation = createEffectFoundation({
+	observability: {
+		enabled: false,
+		classifyError: () => ({ outcome: 'failed' as const, errorCode: 'DOCUMENT_OPERATION_FAILED' }),
+	},
+	checkPermission: (host: Host) =>
+		host.actor.length > 0 ? Effect.void : Effect.fail(new AccessDenied()),
+	writeAudit: (host: Host, entry: AuditEntryInput) =>
+		Effect.gen(function* () {
+			const writer = yield* DocumentWriter
+			yield* writer.audit(host.actor, entry)
+		}),
+})
+const keyInput = z.object({ key: z.string().min(1) })
+const renameInput = keyInput.extend({ title: z.string().trim().min(1) })
+const titleResult = z.string().transform((title) => ({ title }))
+
+export const documents = foundation.Query({
+	context: (host: Host) => host,
+	operations: ({ query }) => ({
+		label: query({
+			input: keyInput,
+			result: z.string(),
+			handler: async (input) => `Document ${input.key}`,
+		}),
+		preview: query({
+			input: keyInput,
+			result: titleResult,
+			permission: 'documents:read',
+			handler: (input, host) =>
+				Effect.gen(function* () {
+					const reader = yield* DocumentReader
+					return yield* reader.title(input.key, host.actor)
+				}),
+		}),
+		title: query({
+			input: keyInput,
+			result: titleResult,
+			permission: 'documents:read',
+			handler: Effect.fn('documents.title')(function* (
+				input: z.output<typeof keyInput>,
+				host: Host,
+			) {
+				const reader = yield* DocumentReader
+				return yield* reader.title(input.key, host.actor)
+			}),
+		}),
+	}),
+})
+export const documentCommands = foundation.Command({
+	context: (host: Host) => host,
+	operations: ({ command }) => ({
+		rename: command({
+			input: renameInput,
+			result: titleResult,
+			classification: 'business',
+			permission: 'documents:write',
+			handler: (input, host) =>
+				Effect.gen(function* () {
+					// A nested query stays in the same Effect; no inner runner.
+					yield* documents.exec('title', { key: input.key }, host)
+					const writer = yield* DocumentWriter
+					yield* writer.rename(input.key, input.title, host.actor)
+					return input.title
+				}).pipe(
+					Effect.catchTag('DocumentMissing', () => Effect.fail(new RenameRejected())),
+					Effect.withSpan('documents.rename'),
+				),
+			guard: (host) => (host.actor.length > 0 ? Effect.void : Effect.fail(new AccessDenied())),
+			middleware: ({ next }) => next().pipe(Effect.withSpan('documents.command')),
+			audit: ({ command: input, result }, host) => ({
+				actorId: host.actor,
+				operation: 'documents.rename',
+				aggregate: { type: 'document', id: input.key },
+				metadata: { title: result.title },
+			}),
+		}),
+	}),
+})
+```
+
+### Request services and shared API setup
+
+Construct the services once in each shared builder provider. Endpoint handlers
+do not call `Context.make`, `Effect.runPromise`, or an extra execution helper.
+The database Promise wrappers below intentionally preserve unexpected database
+failures as defects. For external integrations with expected failures, use
+`Effect.tryPromise` and return your own typed error.
+
+`mapError` projects an expected failure to a small `ConvexError` payload. It
+receives `unknown`, so narrow it before projection. Defects, interruption,
+and combined causes do not become expected failures through this hook; the
+adapter preserves those failure causes. The registered function still fails,
+which is required for mutation rollback.
+
+```ts
+function readerFor(ctx: QueryCtx): Context.Context<DocumentReader> {
+	return Context.make(DocumentReader, {
+		title: (key, actor) =>
+			Effect.gen(function* () {
+				const document = yield* Effect.promise(() =>
+					ctx.db
+						.query('documents')
+						.withIndex('by_owner_key', (q) => q.eq('owner', actor).eq('key', key))
+						.unique(),
+				)
+				if (!document) return yield* Effect.fail(new DocumentMissing())
+				return document.title
+			}),
+	})
+}
+function writerFor(ctx: MutationCtx): Context.Context<DocumentWriter> {
+	return Context.make(DocumentWriter, {
+		rename: (key, title, actor) =>
+			Effect.gen(function* () {
+				const document = yield* Effect.promise(() =>
+					ctx.db
+						.query('documents')
+						.withIndex('by_owner_key', (q) => q.eq('owner', actor).eq('key', key))
+						.unique(),
+				)
+				if (!document) return yield* Effect.fail(new DocumentMissing())
+				yield* Effect.promise(() => ctx.db.patch(document._id, { title }))
+			}),
+		audit: (actor, entry) =>
+			Effect.promise(() =>
+				ctx.db.insert('audits', {
+					actor,
+					operation: entry.operation,
+					documentKey: entry.aggregate.id,
+				}),
+			).pipe(Effect.asVoid),
+	})
+}
+function authenticatedHost(ctx: QueryCtx) {
+	return Effect.gen(function* () {
+		const identity = yield* Effect.promise(() => ctx.auth.getUserIdentity())
+		if (!identity) return yield* Effect.fail(new AccessDenied())
+		return { actor: identity.tokenIdentifier }
+	})
+}
+function projectExpectedError(error: unknown) {
+	if (error instanceof DocumentMissing || error instanceof RenameRejected)
+		return new ConvexError({ code: 'DOCUMENT_NOT_FOUND' })
+	if (error instanceof AccessDenied) return new ConvexError({ code: 'ACCESS_DENIED' })
+	return new Error('Document operation failed', { cause: error })
+}
+const queryApi = effectApiBuilder(nativeQuery, {
+	services: readerFor,
+	mapError: projectExpectedError,
+})
+const mutationApi = effectApiBuilder(nativeMutation, {
+	services: (ctx) => Context.merge(readerFor(ctx), writerFor(ctx)),
+	mapError: projectExpectedError,
+})
+```
+
+### Consume the domain operations in the API
+
+The Convex callback remains `(ctx, input)`; the domain callback and executor
+use input before context/host. Both endpoints are normal native registrations
+with argument and return validators. Each handler authenticates the request
+and returns the domain Effect. The adapter supplies the services required by
+the complete nested program.
+
+```ts
+export const documentTitle = queryApi({
+	args: { key: v.string() },
+	returns: v.object({ title: v.string() }),
+	handler: (ctx, input) =>
+		Effect.gen(function* () {
+			const host = yield* authenticatedHost(ctx)
+			return yield* documents.exec('title', input, host)
+		}),
+})
+export const renameDocument = mutationApi({
+	args: { key: v.string(), title: v.string() },
+	returns: v.object({ title: v.string() }),
+	handler: (ctx, input) =>
+		Effect.gen(function* () {
+			const host = yield* authenticatedHost(ctx)
+			return yield* documentCommands.exec('rename', input, host)
+		}),
+})
+```
+
+## Types and schema boundaries
+
+The command accepts `z.input<typeof renameInput>`. Its handler sees
+`z.output<typeof renameInput>`, so the title has already been trimmed. The
+handler returns a string, which is the input of `titleResult`; the registry's
+final result is `{ title: string }`, the output of that transform. Middleware
+`next()` returns the handler result before the final result parser, so wrap
+or transform that value according to the result schema's input contract.
+
+TypeScript preserves the selected operation's success, expected error, and
+service requirements. The title query requires `DocumentReader`; rename
+requires `DocumentReader | DocumentWriter` and can fail with `AccessDenied`
+or `RenameRejected`. The API builder checks that its provider supplies those
+services. A reader-only provider cannot register rename, and an incompatible
+handler result cannot pass its declared native return validator.
+
+This is server-side Effect composition. Generated Convex references retain
+native argument/result types and visibility; they do not carry Effect's typed
+error or service channels over the transport. Clients receive ordinary Convex
+results or errors.
+
+For inferred declarations, put `handler` and `guard` before `middleware`, as
+above. Middleware-first declarations need explicit callback and error/service
+annotations where inference cannot recover the later handler's channels.
+`Effect.fn` accepts typed function arguments; `Effect.gen` accepts a generator
+whose yielded Effects determine its channels. Use `(input, context) =>
+Effect.gen(function* () { ... })` when those values come from the declaration.
+A constructed `Effect.gen` program cannot itself receive handler arguments.
+
+## Hooks, replay, and execution scope
+
+A command runs input parsing, observation setup and context resolution, then
+permission checking, preparation, middleware, shared and operation guards,
+handler, final result parsing, audit construction, aggregate checking, audit
+writing, and completion. Observation records the outcome. Query permission
+checking runs before its context resolver, followed by middleware, guards,
+handler, and result parsing. Command audit/completion hooks do not exist on
+queries.
+
+Optional command `prepare(context, input)` returns `{ kind: 'execute',
+complete }` or `{ kind: 'replay', result }`. The completion callback receives
+the parsed final result. Permission checking still precedes replay. A replay
+result is parsed with `replayResult` when supplied, otherwise with `result`,
+and skips middleware, guards, handler, audit writing, and completion.
+Middleware receives `operation`, parsed `input` (also `command`), `context`,
+and `next`; it may provide an enriched context to `next({ context })`.
+Each execution allows `next` once. Audit construction sees the original domain
+context, and the audit writer sees the original trusted host.
+
+The provider may return a `Context`, a Promise of a Context, or an Effect that
+builds a Context. It runs separately for every native invocation. The shared
+runner opens an Effect scope, evaluates the provider and handler, and awaits
+scope finalizers before returning or throwing. Use `Effect.acquireRelease`
+inside a provider for resources that actually need cleanup. Nested domain
+operations share that runner and scope; do not run them independently inside
+handlers. Cleanup failure remains an endpoint failure, including when it
+combines with a handler failure.
+
+## Convex boundaries and observed support
+
+A domain query is a reusable read operation; its name does not choose the
+native function kind. A native Convex query must perform deterministic database
+reads. Native mutations can write, and a failed command, result validator,
+audit writer, completion hook, or awaited cleanup rolls back that mutation's
+writes. Actions are the place for HTTP and other external integrations.
+An action's separate `ctx.runMutation` calls are separate transactions: a
+later failure does not undo an earlier successful mutation.
+
+The packed public facade was compiled and executed under npm and Bun with
+Effect 4.0.1 and `convex-helpers` 0.1.123. Legacy packed consumers also ran with
+Effect absent. Local Convex 1.45.0 checks exercised ordinary, generator, and
+named-function query composition; request cleanup; expected and combined
+failures; mutation validation and lifecycle rollback; and an action using
+loopback HTTP with separate mutation transactions. `Effect.withSpan` was
+accepted in those programs; this does not establish exported telemetry,
+background fibers, arbitrary concurrency, or every Effect runtime capability
+in Convex.
+
+The standalone packed compiler includes `ESNext.Disposable` in its library
+set for Effect 4 declarations. If your project's TypeScript environment does
+not already provide those globals, include that library as well.
+
+## Adopt one domain at a time
+
+Keep existing Promise registries and API endpoints while adding the optional
+facade for a new domain. Move each operation's handler beside its schemas and
+hooks, switch domain callbacks to input-first arguments, and return the new
+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 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`,