cvx-kit 0.1.7 → 0.1.8

package/docs/commands.md

@@ -1,105 +1,30 @@
-# `cvx-kit/components/foundation` — the audited command protocol
+# Commands — declare handlers once, execute through Effect
 
-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.
+Use `createEffectFoundation` from `cvx-kit/effect` for application commands.
+The Foundation binds observability, permissions, and audit writing once. Each
+registry injects its domain context and declares schemas, handler, and hooks
+inside `command({...})`. `exec(operation, input, host)` returns a lazy Effect;
+execution does not accept a replacement handler.
 
-## Mounting and declaring
+Install the Effect peer before importing this facade:
 
-```ts
-// convex/convex.config.ts
-import { defineApp } from 'convex/server'
-import foundation from 'cvx-kit/components/foundation/convex.config'
-
-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),
-	},
-})
+```sh
+bun add effect@'>=4.0.1 <5'
 ```
 
-Host code consumes the Foundation **only through this facade** — never deep
-imports of the component's internal modules.
-
-For new domains, [the optional Effect facade](./effect.md) offers cohesive
-command/query entries with handlers in the declaration and injectable context.
-The complete guide covers ordinary, `Effect.gen`, and `Effect.fn` handlers,
-nested domain integrations, and shared API execution.
-
-## Incremental migration to Effect
+The old `Foundation.Command` constructor and `exec({ operation, handler })`
+API are **deprecated**, retained for compatibility with existing consumers.
+Their [compatibility reference](./commands-legacy.md) is for migration and
+maintenance. The Foundation component, Query kernel, observability, and
+transaction result helpers remain available. No component mount is required
+by `createEffectFoundation` itself.
 
-The existing Foundation keeps separate operation and handler declarations,
-context-first handler arguments, and Promise executors. No existing consumer
-needs to change when another domain adopts `cvx-kit/effect`.
-
-This legacy factory accepts the mounted Foundation component and defines all
-of its domain dependencies through the host context:
-
-<!-- packed-effect-example -->
-
-```ts
-import { Foundation, type AuditEntryInput } from 'cvx-kit/components/foundation'
-import { z } from 'zod'
-
-type Host = {
-	actorId: string
-	rename: (id: string, title: string) => Promise<void>
-	appendAudit: (entry: AuditEntryInput) => Promise<void>
-}
-const input = z.object({ id: z.string(), title: z.string() }).strict()
-const result = z.object({ ok: z.literal(true) }).strict()
-
-export function createLegacyRename(component: ConstructorParameters<typeof Foundation>[0]) {
-	const { Command } = new Foundation(component, {
-		observability: {
-			enabled: false,
-			classifyError: () => ({ outcome: 'failed', errorCode: 'RENAME_FAILED' }),
-			writeAudit: (host: Host, entry) => host.appendAudit(entry),
-		},
-	})
-	const typed = Command.withContext<Host>()
-	const operations = {
-		rename: typed.operation({
-			command: input,
-			result,
-			classification: 'business',
-			audit: ({ command }, host) => ({
-				operation: 'documents.rename',
-				actorId: host.actorId,
-				aggregate: { type: 'document', id: command.id },
-			}),
-		}),
-	}
-	const commands = new Command<Host, typeof operations>(operations)
-	return commands.exec({
-		operation: 'rename',
-		handler: async (host, command) => {
-			await host.rename(command.id, command.title)
-			return { ok: true }
-		},
-	})
-}
-```
+## Declare commands
 
-The replacement keeps the handler beside its schemas and audit policy. It
-uses input-first, context-second callbacks and returns a lazy Effect from
-`exec(operation, input, host)`, including when the handler is ordinary async:
+This complete example uses an ordinary async handler. It still executes through
+the Effect lifecycle, with input-first, context-second handler arguments.
+`context` resolves per invocation; shared registries must not capture an
+authenticated request context.
 
 <!-- packed-effect-example -->
 
@@ -125,10 +50,11 @@ const foundation = createEffectFoundation({
 export const commands = foundation.Command({
 	context: (host: Host) => host,
 	operations: ({ command }) => ({
-		rename: command({
+		'documents.rename': command({
 			input,
 			result,
 			classification: 'business',
+			aggregates: ['document'],
 			handler: async (input, context) => {
 				await context.rename(input.id, input.title)
 				return { ok: true as const }
@@ -141,371 +67,107 @@ export const commands = foundation.Command({
 		}),
 	}),
 })
-```
-
-Pass the resulting Effect to a handler registered through a shared
-`effectApiBuilder` or `effectZodApiBuilder`; see [the complete domain-to-API
-example](./effect.md). Domain composition does not start a separate runner.
-Ordinary throws and rejected Promises become defects; use `Effect.fail` or
-`Effect.tryPromise` for an inferred typed error channel. The native Convex
-reference retains argument/result types, but does not transport the server's
-Effect error and service types.
-
-Both facades share command lifecycle ordering, validation, audit, and replay
-rules. Commands that write remain inside a Convex mutation, and failures must
-escape that mutation to roll its writes back.
-
-## 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'
-import { zid } from 'cvx-kit/zod-table'
-import type { MutationCtx } from '../../_generated/server'
-
-const typed = Command.withContext<MutationCtx>()
-
-const operations = {
-	'documents.rename': typed.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 }
-	},
-})
+export const executeRename = (value: z.input<typeof input>, host: Host) =>
+	commands.exec('documents.rename', value, host)
 ```
 
-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.
+`classification` and `audit` are mandatory. Input decoding precedes the handler;
+final result decoding follows middleware. Handlers return the result schema's
+input; audit and completion receive its validated output. Ordinary values,
+Promises, `Effect.gen`, and `Effect.fn` all work inside the declaration. Throws
+and rejected Promises become defects; use `Effect.fail` or `Effect.tryPromise`
+for expected failures in the inferred error channel.
 
-## What one execution does, in order
+## Execute at the API boundary
 
-1. **Parse the command** through the operation's `command` schema (strict zod).
-2. **Observe**: start the observation clock.
-3. **Permission check** — if the operation declares `permission`, the
-   Foundation's injected `checkPermission(ctx, { permission, operation })`
-   runs; throw to deny. Declaring a permission with no injected checker
-   **fails closed** (`COMMAND_PERMISSION_NOT_CONFIGURED`).
-4. **Prepare**, when configured: obtain an invocation-local replay decision
-   or completion closure. Replay validates its durable result, then goes
-   directly to observation, skipping middleware, both guards, handler and audit.
-5. **Middleware and guards** — registry middleware wraps operation middleware,
-   which wraps both guards and the handler. The default guard is the
-   registry-wide guard passed as the Command's second
-   argument (`new Command(operations, { guard })`), if any.
-   Then the operation's own `guard(ctx, command)` checks
-   preconditions like state-machine legality, ownership beyond roles, or
-   invariants over the parsed command. Throw to deny — nothing has run yet,
-   so a denial is always clean.
-6. **Run the handler and unwind middleware**; parse the final chain output
-   through the `result` schema exactly once. Middleware sees schema inputs;
-   audit, completion, and the executor receive validated schema outputs.
-7. **Audit**: call the operation's `audit({ command, result }, ctx)`. If it
-   returns non-null, the entry (plus the operation's `classification`) is
-   written through the injected `writeAudit` — **in the same transaction** as
-   the handler's writes. Returning `null` skips the audit (the ontology
-   convention: failures are not audited). When the operation declares
-   `aggregates: [...]`, an audit whose `aggregate.type` is not in that
-   allowlist throws (`COMMAND_AGGREGATE_NOT_DECLARED`) — the audit
-   vocabulary is enforced, not advisory. The per-operation catalog is
-   introspectable as `commands.aggregates` for tests.
-8. **Complete**: await the closure returned by `prepare`, including when audit
-   returns null. A failure propagates inside the observation boundary.
-9. **Emit the observation**: `{ operation, classification, outcome,
-errorCode?, durationMs }` — completed, denied, or failed per
-   `classifyError`.
+Wrap the application's trusted `authMutation` once with `effectZodApiBuilder`
+in `convex/functions.ts`, then return the command Effect from the endpoint:
 
-### Guards and permissions
+This wiring sketch assumes the existing authenticated constructor, command
+registry, schemas, and a mapping to the registry's dependencies. Keep the
+application's existing function export name:
 
 ```ts
-// convex/foundation.ts — permission semantics are host policy, injected once
-export const { Command, Query, observability } = new Foundation(
-  components.foundation,
-  {
-    observability: { ... },
-    checkPermission: (ctx, { permission }) =>
-      requirePermission(ctx.identity, permission),   // throw to deny
-  },
-)
-
-// domain/<module>/commands.ts
-const operations = {
-  '<entities>.publish': Command.operation({
-    command: <entities>.commandInput.extend({ id: zid('<entities>') }),
-    result: z.object({ ok: z.literal(true) }).strict(),
-    classification: 'business',
-    permission: '<domain>.manage',                    // checked first
-    aggregates: ['<aggregate-type>'],                 // audit vocabulary allowlist
-    guard: async (ctx, command) => {                  // precondition, pre-handler
-      const row = await requireTenantReference(ctx.tenant, () => ctx.db.get(command.id))
-      if (row.state !== 'draft') errors.throw({ code: 'INVALID_STATE' })
-    },
-    audit: ({ command }) => ({ ... }),
-  }),
-} as const
-
-const commands = new Command<MutationCtx, typeof operations>(operations, {
-  guard: (ctx) => assertNotReadonlyWindow(ctx),       // registry-wide default
+// convex/functions.ts
+export const authMutation = effectZodApiBuilder(base.authMutation, {
+	context: (ctx) => ({ commands: commands.withContext(toCommandContext(ctx)) }),
 })
-```
-
-Guards deny by throwing; a denial before the handler never needs rollback
-because nothing has executed. Keep guards read-only — a guard that writes is
-a handler in disguise.
-
-### Middleware — composable, next()-based
 
-For wrap-around concerns (timing, tracing, context enrichment) that two
-disconnected callbacks can't express, both kernels take
-Express/TanStack-style middleware. The chain runs **inside** the pipeline's
-invariants: after the permission check, around [guards → handler], before the
-result-schema parse, aggregate allowlist, and audit — so middleware can
-never skip authorization, return an invalid result, or desynchronize audit
-from effects.
-
-```ts
-const timing = Command.middleware(async ({ operation, next }) => {
-  const started = Date.now()
-  const result = await next()                       // inner middleware → guards → handler
-  observability.observe // (or your own sink)
-  console.info(`${operation} took ${Date.now() - started}ms`)
-  return result
-})
-
-const withVendor = Command.middleware(async ({ context, next }) =>
-  next({ context: { vendor: await loadVendor(context) } }))  // enriches downstream ctx
-
-const commands = new Command<Ctx, typeof operations>(operations, {
-  guard: (ctx) => assertNotReadonlyWindow(ctx),
-  middleware: [timing],                             // registry-wide, outermost
-})
-
-'<entities>.publish': Command.operation({
-  ...,
-  middleware: [withVendor],                         // per-operation, inside registry chain
-  guard: (ctx, command) => { /* ctx.vendor available here */ },
+// convex/api/documents.ts
+export const rename = authMutation({
+	args: renameInput,
+	returns: renameResult,
+	handler: (ctx, input) => ctx.commands.exec('documents.rename', input),
 })
 ```
 
-Order: registry middleware (array order) → operation middleware → default
-guard → operation guard → handler. `next()` returns the downstream result;
-`next({ context })` merges enrichment into the context handed to inner
-middleware, guards, and the handler. Skipping `next()` short-circuits
-(guards and handler never run — the returned value still must satisfy the
-result schema); calling it twice throws `COMMAND_MIDDLEWARE_NEXT_REUSED`.
-Whatever leaves the chain is parsed through the operation's strict result
-schema — a middleware cannot fabricate an invalid result.
-
-### Schema-inferred callbacks and context extensions (0.1.3)
-
-`Command.withContext<Ctx>()` binds the host context for operation definitions.
-Its `operation()` infers parsed command fields, validated audit result fields,
-and the declared aggregate vocabulary. Operation middleware is contextual:
-write inline callbacks without `Command.middleware`, whose legacy low-level
-command and result boundary intentionally remains unknown.
-
-```ts
-const typed = Command.withContext<Ctx>()
-const operations = {
-	rename: typed.operation({
-		command: z.object({ title: z.string().transform((value) => value.length) }),
-		result: z.object({ ok: z.boolean() }),
-		classification: 'business',
-		aggregates: ['document'],
-		guard: (ctx, command) => requireTitleLength(ctx, command.title), // number
-		middleware: [
-			async ({ command, next }) => {
-				const result = await next() // { ok: boolean }, before validation
-				logLength(command.title)
-				return result
-			},
-		],
-		audit: ({ command, result }, ctx) => ({
-			operation: 'rename',
-			actorId: ctx.actorId,
-			aggregate: { type: 'document', id: String(command.title) },
-			metadata: { ok: result.ok },
-		}),
-	}),
-}
-const middleware = typed.registryMiddleware(operations, async (input) => {
-	if (input.operation === 'rename') {
-		input.command.title.toFixed() // discriminator retains schema correlation
-	}
-	return input.next()
-})
-const commands = new Command<Ctx, typeof operations>(operations, {
-	middleware: [middleware],
-})
-```
-
-Bind registry middleware to the same registry it describes. A heterogeneous
-registry callback returns a union; narrowing `input.operation` preserves
-the matching `input.command` and `input.next()` result type.
-Reusing it with a different operation definition throws
-`COMMAND_MIDDLEWARE_REGISTRY_MISMATCH` before the typed callback runs.
-
-To propagate a required middleware extension to guards and handlers, use
-`Command.withContext<Ctx, { traceId: string }>()`. Its operations require a
-nonempty middleware tuple; the first layer must pass the declared extension
-to `next({ context: { traceId } })` whenever it runs the downstream chain.
-Later layers, guards and handlers see `Ctx & { traceId: string }`.
-Audit and prepare receive the original context. The original context object
-is not mutated. Short circuits still undergo final result validation.
-
-### Transactional completion and replay (0.1.3)
-
-Use `prepare(ctx, parsedCommand)` for host-owned idempotency. It runs after
-permission and returns either `{ kind: 'replay', result: durableValue }` or
-`{ kind: 'execute', complete: async validatedResult => { ... } }`.
-The completion closure captures per-invocation state, including a fingerprint
-derived from the parsed command and authenticated actor. Do not cache that
-state in a shared context or module variable.
-
-```ts
-prepare: async (ctx, command) => {
-  const key = scopedKey(ctx.actorId, command.idempotencyKey)
-  const fingerprint = fingerprintOf(command)
-  const receipt = await loadReceipt(ctx, key)
-  if (receipt) {
-    if (receipt.fingerprint !== fingerprint) throw new Error('KEY_REUSED')
-    return { kind: 'replay', result: receipt.result }
-  }
-  return {
-    kind: 'execute',
-    complete: async result => {
-      await saveReceipt(ctx, { key, fingerprint, result })
-    },
-  }
-},
-```
-
-Storage, actor/tenant scoping, fingerprint comparison, retention, and conflict
-policy remain host responsibilities. Put authorization required on replay in
-the injected permission checker or prepare lookup; both guards are skipped
-on replay. A permission slug without a checker still fails closed. Ordinary
-middleware short-circuiting is not this replay path and still audits.
-
-Replays are parsed through `result` by default. If that schema transforms its
-input, store the completion callback's validated output and supply
-`replayResult` with an output validator (for example `z.number().int()` when
-`result` transforms a string into a number). This prevents reapplying an input
-transform to an already transformed durable result. An invalid replay fails
-inside observation; successful replay does not invoke completion again.
-
-Completion is awaited after result validation, audit resolution, aggregate
-validation, and audit writing, even on audit-null paths. Errors from prepare,
-replay validation, audit, or completion propagate and are passed to the host's
-error classifier. Observation success means this command finished; the
-enclosing mutation has not necessarily committed yet.
-
-The Query kernel takes the same shape: `new Query({ defaults, middleware,
-execute })` plus per-executor `middleware: [...]`, with `Query.middleware`
-as the typing helper. Kernel middleware runs before executor middleware,
-inside the host's injected `execute` policy.
-
-For atomic rollback, let failures escape the enclosing Convex mutation.
-Catching and swallowing a failure inside that mutation can commit earlier
-business, audit, and completion writes. Rethrow after effects, or use the
-effect-aware `executeResultBoundary` below. External I/O in actions is not
-rolled back; these transaction guarantees concern Convex mutation writes.
-
-### 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
-// destructured from the Foundation facade, like everything else
-const { executeResultBoundary, projectResult } = new 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. Use `Command.withContext<MutationCtx>()` for typed callbacks and construct
-   the Command with a compatible host context. Legacy `Command.operation`
-   keeps its low-level callback signature. Commands with writes 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`.
+Injection is optional. Use explicit `exec(name, input, context)` when appropriate.
+The value supplied to `withContext` matches the registry's resolver, and can be
+any declared dependency type. See [optional context injection](./command-context.md)
+for a complete compiled example, input-only handlers, multiple command groups,
+and feature organization for applications with many entities. Use authenticated
+constructor fields for identity and tenant information, rather than client
+arguments. Services may also be provided by the adapter when the program uses
+Effect services. See [the complete domain-to-API example](./effect.md) and
+[authenticated builder wiring](./auth.md).
+
+The builder runs the Effect in an invocation scope and awaits finalizers.
+Nested commands and queries compose into the same Effect; do not start an
+inner `Effect.runPromise`. Native Convex references retain argument/result
+types, but do not transport Effect's server-side error and service channels.
+
+## Lifecycle and hooks
+
+1. Decode `input`, start observation, then resolve invocation-local context.
+2. Check a declared `permission` through the Foundation's injected
+   `checkPermission(host, { permission, operation })`. A missing checker fails
+   closed. The policy receives the original host.
+3. Run `prepare(context, input)` if configured. Replay validates the stored
+   result and skips middleware, guards, handler, audit writing, and completion.
+4. Run the operation's `middleware`, wrapping `defaults.guard(context)`, the
+   operation's `guard(context, input)`, and `handler(input, context)`.
+5. Decode the middleware chain's final result, derive `audit({ command, result },
+   context)`, enforce `aggregates`, and call the injected `writeAudit(host, entry)`
+   when the audit is non-null.
+6. Await the completion closure from `prepare`, then finish observation.
+
+Effect middleware is a callback returning a value, Promise, or Effect, rather
+than the legacy facade's middleware arrays. `next()` returns an Effect;
+`next({ context })` merges a context extension for downstream guards and the
+handler. Prepare and audit receive the original domain context. Short circuits
+still validate and audit; calling `next()` twice fails. Defaults support a
+registry guard; declare middleware per operation.
+
+Guards should be read-only. Put authorization required on replay in the
+permission policy or prepare lookup, because replay skips both guards. When
+`result` transforms its input, store the validated output in completion and
+supply a `replayResult` output validator to avoid applying the transform twice.
+Use `effectTransactionalIdempotency` for receipt-backed replay;
+[domain integrations](./domain-operations.md) cover idempotency, workflows,
+CRUD, and selected operation tools.
+
+Commands that write run inside Convex mutations. Let failures escape the
+mutation so Convex rolls back business, audit, and completion writes. Returning
+a failure value after a write can commit that write. Observation completion is
+command completion, not proof that the enclosing transaction committed.
+
+## Migrate the deprecated API
+
+- Replace the command facade from `new Foundation(...)` with
+  `createEffectFoundation(...)`. Move `writeAudit` out of the legacy
+  `observability` options into the Effect Foundation's top-level options.
+- Replace `new Command(operations, defaults)` with
+  `foundation.Command({ context, operations: ({ command }) => ({ ... }), defaults })`.
+- Use `input` instead of the old schema property `command`. Move each handler
+  from executor options into its operation's `command({...})` declaration.
+- Change handlers from `(context, input)` to `(input, context)`. Hooks retain
+  their documented context-first or resolution-first signatures.
+- Replace Promise executor factories with `exec(operation, input, host)` and
+  return the resulting Effect through a shared API builder. Keep authentication,
+  tenant policy, triggers, and native validators on that builder.
+
+Existing consumers can migrate one domain at a time. Only the Effect API is
+recommended for new command code; the deprecated facade remains callable until
+a separately announced breaking release. See the [old API reference](./commands-legacy.md)
+when maintaining a domain that has not migrated yet.

package/docs/conventions.md

@@ -121,7 +121,7 @@ another file's function to shorten an import.
 | `schema.ts`        | `defineSchema(domainTables)`                                                                                           | table definitions, validators                                    |
 | `functions.ts`     | the single `createAuthFunctions<DataModel>()` call and its exported constructors                                       | handlers, business policy beyond the injected config             |
 | `triggers.ts`      | `createTriggers()`, `timestamps`/`appendOnly`/`noDelete` registrations, calls to per-entity `register<Entity>Triggers` | trigger _logic_ for a specific entity (that lives in the entity) |
-| `foundation.ts`    | the single `new Foundation(...)`, destructured exports                                                                 | command definitions                                              |
+| `foundation.ts`    | the single `createEffectFoundation(...)`, bound command/query exports                                                  | command definitions                                              |
 | `<component>.ts`   | `new <Client>(components.<name>)` + minimal admin plumbing                                                             | workflow/business definitions                                    |
 | `http.ts`          | route registration delegating request handling to the owning domain                                                    | webhook business logic                                           |
 | `crons.ts`         | `cronJobs()` declarations targeting `internal.domain.<entity>...`                                                      | handler logic                                                    |
@@ -191,14 +191,18 @@ compile. Numeric limits and durations the entity owns also live here.
 
 ### `domain/<entity>/commands.ts` — every state change
 
-1. The frozen operation registry: `Command.operation({ command, result,
-classification, audit })` per operation, keys `'<entity>.<verb>'`.
-2. One `new Command<Ctx, typeof operations>(operations)`.
-3. Exported executors: `export const execute<Verb><Entity> = commands.exec(...)`.
+1. One `Command({ context, operations: ({ command }) => ({ ... }) })` using
+   the bound constructor from `createEffectFoundation` (`cvx-kit/effect`).
+2. Each entry declares `command({ input, result, classification, handler, audit })`,
+   with keys `'<entity>.<verb>'`. Handlers receive `(input, context)`.
+3. Exported domain functions return `commands.exec(operation, input, host)`;
+   the shared Effect API builder executes that Effect at the authenticated boundary.
 4. Private handler helpers at the bottom.
 
 Audit derivation lives here, next to the operation it describes. No reads
 that belong in `queries.ts`; no pure predicates that belong in `rules.ts`.
+The Promise command facade is deprecated; see `commands-legacy.md` only for
+maintaining existing code. New implementations follow `commands.md`.
 
 ### `domain/<entity>/queries.ts` — domain reads
 
@@ -317,3 +321,9 @@ component internals (anything below a component's client facade),
 created before <epoch>.`) — never narration of the next line.
 - One entity concept per file; when a file serves two purposes, split it
   along the anatomy in §2.
+
+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).